Task Sizing Guide

Official router: effort-scales.yaml (wall_clock_tshirt).

Use these definitions consistently across gap analyses and remediation plans. Effort is wall-clock time for one developer, including testing and PR review.

For active WIP progress tracking under AI-assisted delivery, use the separate Fibonacci scale — see plan-effort-estimate and the handoff rules in the taxonomy.

Effort Scale

Effort	Wall Clock	Characteristics	Examples
Trivial	< 1 hour	Config change, single file, no design decision, no tests needed	Add .dockerignore, toggle a flag, add a dependency to pyproject.toml
Small	Half day – 1 day	Single file or small module, clear pattern to follow, tests needed but straightforward	Create a Dockerfile, add coverage threshold to CI, wire a health endpoint, add a pre-commit hook
Medium	1–3 days	Multiple files, some design decisions, may need coordination, tests + docs	Implement OIDC auth, create a storage adapter, write a Terraform module, create an integration test suite
Large	3–5 days	Cross-cutting change, new infrastructure, external approvals, significant testing	Full CI/CD pipeline with environment promotion, database migration with parity tests, security audit + remediation
Decision	Variable	Blocked on a choice that affects downstream work. Not effort — it's a gate.	GitHub vs Azure DevOps, database backend choice, container topology

Sizing Rules

• Size includes writing tests. If a task says "Small" but needs 20 tests, it's Medium.
• Size includes PR review time. A 1-hour code change with a 2-hour review cycle is Small, not Trivial.
• External dependencies (Azure subscription provisioning, Entra ID registration, security review) add lead time but not effort. Note lead time separately.
• If a task requires a decision that hasn't been made, mark the decision as a separate item and note the dependency.
• Phase effort totals (days/weeks) are judgement-based ranges — do not sum T-shirt labels into fake day counts.

Task Description Rules

Each task in the plan should be:

• Action-oriented — starts with a verb: Create, Implement, Add, Replace, Configure, Wire, Remove
• Specific — names the file, module, tool, or endpoint affected
• Bounded — a reader knows when it's done
• Independent — completable without needing other tasks in the same phase (within-phase parallelism)

Good: "Create storage/postgresql/adapter.py implementing the 3 storage protocols (GatewayDecisionLog, JournalAndLedger, SnapshotStore) with PostgreSQL types (JSONB, SERIAL, TIMESTAMPTZ)."

Bad: "Set up the database layer."

Status Tracking

See plan-status.yaml for the official crosswalk.

Symbol	Status	Meaning
⬜	Not started	Work has not begun
🔶	In progress	Actively being worked on (optionally: branch name, PR number)
✅	Complete	Merged and validated (optionally: commit SHA, PR number, Jira ticket)
❌	Blocked	Cannot proceed — state the blocker
🚫	Cancelled	No longer needed — state why

Table Format

#	Task	Effort	Jira	Status
X.Y	Action verb + specific target — Detail about scope, files affected, approach.	Small		⬜ Not started

WIP handoff

When this plan becomes active execution, add a *.effort.json sidecar beside the plan markdown (e.g. docs/wip/<plan-slug>.effort.json). Re-size with the Fibonacci scale per effort-scales.yaml — do not copy T-shirt labels literally.