Planning And Task Breakdown

Planning and Task Breakdown

Overview

Read .forge/prd.md, .forge/architecture.md, and .forge/contracts/ to produce .forge/tasks.yaml — a sized, dependency-ordered list of tasks where each task is a thin vertical slice through all layers. Output feeds incremental-implementation.

When to Use

• .forge/prd.md and .forge/architecture.md both exist
• Ready to break work into implementable tasks before coding starts
• Need to identify dependencies and parallelize work

When NOT to Use

• Architecture doesn't exist yet — run architecture-and-contracts first
• PRD is not complete — gaps produce tasks with unknown scope
• Single-module change with no integration — implement directly with tdd

Common Rationalizations

Red Flags

• Tasks that touch more than 3 modules (not a vertical slice — split it)
• No acceptance criteria per task (untestable)
• No dependency graph (implementation order unknown)
• Task descriptions name files/functions instead of behaviors
• XL tasks with no breakdown path (too much unknown — spike first)
• All tasks marked "no dependencies" (integration is being deferred)

Core Process

Step 1: Read the artifacts

Read .forge/prd.md for requirements. Read .forge/architecture.md for components. Read all files in .forge/contracts/ for module interfaces.

Step 2: Identify vertical slices

Each task must be a tracer bullet: a thin but complete path through ALL layers. Not "implement the API" — that's horizontal. Instead: "user can submit a form and see a success message" — that's a vertical slice cutting through UI, API, and storage.

Rules:

• Completed task is demoable or verifiable on its own
• Each slice covers one user story or one acceptance criterion
• Prefer many thin tasks over few thick ones
• Tasks must reference contract names, not file paths

Step 3: Size each task

Step 4: Map dependencies

For each task, list which other tasks must complete first. Build the dependency graph. Identify the critical path and which tasks can run in parallel.

Step 4b: Tag tasks with shaping skills (optional but recommended)

For each task, decide which other forge-skills shape the implementation and add a skills: field. This is read by incremental-implementation before the first test is written, loading the relevant constraints into context at the moment they're needed.

Common patterns:

• UI work touching components → include design-system, accessibility
• Interaction shape decisions (modal vs sheet, expand vs nav) → include interaction-patterns
• New REST endpoints → include api-design
• Migrations or schema changes → include database-design
• Tasks producing observability or alerts → include observability
• Tasks with non-trivial error paths → include error-handling-and-resilience

Omit the field if the task is pure plumbing with no domain-shaping skill applicable. Leaving it blank is fine — incremental-implementation treats skills: as optional and backward compatible.

Step 5: Quiz the user

Present the breakdown. For each task: title, size, dependencies, acceptance criteria. Ask: granularity right? Dependencies correct? Any tasks to merge or split?

Iterate until approved.

Step 6: Write .forge/tasks.yaml

Prepend a forge:meta header (generated_by: planning-and-task-breakdown, generated_at: <ISO 8601 UTC with Z>, depends_on: [.forge/prd.md, .forge/architecture.md, .forge/contracts/*] — paths only, never hashes, generated_from: {.forge/prd.md: <hash>, .forge/architecture.md: <hash>, .forge/contracts/<each-resolved>.md: <hash>} — each upstream's content_hash AT generation time, content_hash: <sha256 first 8 over THIS file's body, excluding the forge:meta block>) — comment-style for YAML (# forge:meta ...).

Co-output rule: tasks.yaml and tasks-summary.md are co-generated in this single skill run. Both files MUST carry the same depends_on AND same generated_from set ([.forge/prd.md, .forge/architecture.md, .forge/contracts/*]). Do NOT write tasks-summary.md with depends_on: [.forge/tasks.yaml] — that creates a silent staleness bug where a PRD edit flips tasks.yaml stale but leaves tasks-summary.md UP_TO_DATE. See forge-dependency-graph: co-output rule.

# forge:meta
#   generated_by: planning-and-task-breakdown
#   generated_at: 2026-05-13T12:00:00Z
#   depends_on: [.forge/prd.md, .forge/architecture.md, .forge/contracts/*]
#   generated_from:
#     .forge/prd.md: <prd.md's content_hash at this moment>
#     .forge/architecture.md: <architecture.md's content_hash at this moment>
#     .forge/contracts/auth-service.md: <hash>   # one entry per resolved glob match
#   content_hash: <first 8 chars of sha256 over THIS file's body>

tasks:
  - id: T001
    title: "User can submit registration form"
    size: M
    phase: 1
    depends_on: []
    contracts: [UserService, SessionService]
    skills: [api-design, design-system, accessibility]   # optional — read by /build before first test
    acceptance_criteria:
      - Given valid email+password, form submission creates a user and redirects to dashboard
      - Given duplicate email, submission returns inline validation error
      - Given network failure, form shows retry option without data loss
    verification:
      - Unit tests for UserService.create() covering success and duplicate cases
      - Integration test: POST /register with valid payload returns 201 + session cookie
      - E2E: form submission with valid data lands on dashboard
    files_likely_affected:
      - UserService (new)
      - registration route handler (new)
      - registration form component (new)
    status: pending          # pending | in_progress | done | split | blocked
    started_at: null
    completed_at: null
    commit: null
    notes: []

  - id: T002
    title: "..."
    depends_on: [T001]
    status: pending
    ...

Step 7: Write .forge/tasks-summary.md

Produce a human-readable summary alongside the YAML. Prepend its own forge:meta header with the same depends_on set as tasks.yaml ([.forge/prd.md, .forge/architecture.md, .forge/contracts/*]) — see the co-output rule above. Use <!-- forge:meta ... --> (Markdown, not YAML comment form).

Contents:

• Day-by-day ship view: which tasks ship on which days (estimated)
• Critical path: the longest dependency chain — this sets the minimum timeline
• Risk days: days with the highest-complexity tasks or most integration points
• Parallel work opportunities: tasks that can run simultaneously with different engineers
• Buffer recommendations: where to add slack based on task size and uncertainty

Verification

• .forge/tasks-summary.md written with ship view and critical path
• All user stories from PRD covered by at least one task
• No task touches more than 3 modules
• Every task has at least 2 acceptance criteria
• Every task has a verification step (what proves it's done)
• Every task has lifecycle fields initialized: status: pending, started_at: null, completed_at: null, commit: null, notes: []
• UI tasks tagged with design-system + accessibility; endpoint tasks tagged with api-design; schema tasks tagged with database-design
• Dependency graph has no cycles
• No XL tasks without a spike or decomposition plan
• Task descriptions use module/contract names, not file paths
• .forge/tasks.yaml written and parseable
• User approved the breakdown before writing the file

Fit-Check

Before declaring done, emit one of:

• A short list of specific fit issues observed (e.g., "Plan produced 4 tasks for what is genuinely a 2-hour single-file change — task overhead exceeds the work; recommend incremental-implementation directly" / "skills: tags don't apply — this is a backend-only project with no design-system or accessibility concerns").
• The explicit line: "No fit issues observed for this use case."

Silence is not allowed. See docs/skill-anatomy.md#fit-check.