writing-plans

name	writing-plans
description	Use when requirements are clear enough to plan and the work spans multiple steps, files, or verification stages

Writing Plans

Overview

Turn requirements into an executable plan with concrete files, tests, and verification. A good plan removes guesswork without pretending the implementation is already done.

Core principle: Every task should be specific enough that an engineer can execute it without inventing missing requirements.

When to Use

Use this skill when:

• The task spans multiple files, phases, or checks
• Requirements are stable enough to plan
• The work benefits from a written execution order

Do not use this skill when:

• The change is small enough to track directly in your harness's plan/progress mechanism, when one exists
• Requirements are still ambiguous
• The user asked to implement immediately and the work is trivial

Before Writing the Plan

1. Read the relevant code, docs, and existing specs.
2. Confirm the scope is one coherent unit of work.
3. Stop and clarify if the plan would depend on guessed requirements.

If the request covers multiple independent changes, split it into separate plans or clearly separated task groups.

Plan Format

When a LOOP.md charter exists for the branch, the plan lives in its "Work plan" section, not a separate doc.

Otherwise, save the plan where the user asked. If they did not specify a location, use:

docs/plans/YYYY-MM-DD-<topic>.md

Start with:

# <Topic> Implementation Plan

**Goal:** <one sentence>
**Scope:** <what this plan covers>
**Non-goals:** <what this plan intentionally avoids>
**Risks:** <key technical or rollout risks>

Then include:

Files

• Create: path/to/new_file
• Modify: path/to/existing_file
• Test: path/to/test_file

Task N:

• Outcome:
• Steps:
  • Write or update the failing test
  • Run the targeted check and confirm the expected failure
  • Implement the minimal change
  • Re-run targeted verification
  • Run broader regression checks if needed
• Verification:
  • exact command
  • expected result
• Dependencies:
  • Task N-1 or none

Planning Rules

• Use exact file paths.
• Prefer tasks that can be reviewed independently.
• Encode test-first thinking when the task changes runtime behavior.
• Include commands that can actually be run from the repo.
• Keep steps concrete: "add parser for X in foo.ts", not "improve parsing".
• Keep unrelated refactors out unless they are required to make the change safe.
• Give each task a risk class; the ADF law defines the high-risk set and its approval requirement.
• Include a back-of-envelope resource sketch for data-plane work (per-request/per-item hot paths).

Execution Handoff

If the plan will be executed in the same session:

• Mirror the task list in your harness's plan/progress mechanism, when one exists
• Keep one task in progress at a time
• Revise the plan if implementation reveals real gaps

Independent sidecar work may run as parallel bounded subagents with non-overlapping ownership; the critical path defaults to the packetized delegation stream (rules of engagement).

Red Flags

• Plans that rely on tool names from another harness
• Tasks that touch the same files from multiple parallel workers
• Missing verification steps
• Hidden migrations, schema changes, or contract changes buried in generic wording
• Placeholder language like "update as needed" or "handle edge cases"