Manual Planning

Manual Planning

Produce Markdown plans that another coding agent can execute without reinterpreting the original conversation. A plan is an execution ledger, not a proposal: it has to stay accurate while it is being worked through, and it has to be readable cold by a session that was not there when it was written.

Anything that can be checked mechanically is checked by a script. Do not hand-verify what check-plan.py verifies.

Scripts

Standard library Python 3 only — no install step. Run with python3 or uv run.

# Create a plan: correct name, correct directory, version stamped from this SKILL.md
python3 scripts/new-plan.py "<title>" [--milestoned] [--dir docs/plans]
                                      [--exclude-locally | --tracked] [--force]

# Validate a plan (read-only). exit 0 = clean, 1 = errors, 2 = warnings only
python3 scripts/check-plan.py <plan-file> [--json] [--strict] [--dir docs/plans]

# Change one task's status, or read every status back
python3 scripts/plan-status.py <plan-file> set <task-id> "<STATUS>"
python3 scripts/plan-status.py <plan-file> show

Each answers --help, which lists every check ID and exit code. Quote the status argument: three of the five task statuses contain a space.

Default Location

docs/plans/YYYY-MM-DD-<name>-plan.md.

The date in the filename is the date of record, which is why the metadata block carries no Created or Last Updated field. new-plan.py produces both the directory and the filename, so neither is a rule you have to remember. Avoid names like notes.md, scratch.md or todo.md.

Plan Tracking

Default to not committing the plan. Follow the repo instead when it already has a convention: if the plan directory holds tracked plans, this project commits them. Commit the plan when the user asks.

If the plan stays untracked and its ?? entry interferes — a plan's own cleanup task validates with git status --porcelain — add the plan directory to .git/info/exclude rather than .gitignore; .gitignore is itself a tracked file, so editing it creates the commit you were avoiding. new-plan.py --exclude-locally does this and stamps Tracking: untracked (locally excluded).

Plan Creation Workflow

1. Gather enough repository context to identify scope, dependencies, test surfaces, and likely risks. Everything you learn here goes in ## Context For A Clean Session — see references/context-and-evidence.md.
2. Create the file with new-plan.py, choosing --milestoned for more than 10 tasks.
3. Fill in the template. Every factual claim carries evidence: a file:line reference, a section reference (SKILL_RULES.md §5), or a re-runnable command.
4. Set Plan Status to QUESTIONS PENDING if clarification is required, then surface the questions to the user. Mirror them in Open Questions.
5. Incorporate the answers, run check-plan.py, and paste its output into ## Plan Self-Check.
6. Set Plan Status to READY FOR APPROVAL only when the checker is clean and the only remaining gate is user approval.

Do not begin implementation until the user approves the plan, unless the user explicitly asks to proceed without approval. When approval is given, replace the ## Approval Gate boilerplate with Approved by <who> on <date>. — the section is a record, not a standing instruction.

Open Question Handling

Open questions are not plan-only notes. When clarification is needed, actively ask the user before marking the plan READY FOR APPROVAL.

1. Use the native question-asking tool (question, ask-user, request-input, or whatever the current harness exposes). Always prefer a structured tool over plain text.
2. If no such tool is available, send a concise formatted message in the conversation.
3. Record both the question and the user's answer in Open Questions.
4. After the user answers, replace the entry with the resolved answer, or the section with None.

Ask only questions that affect correctness, scope, risk, validation, sequencing, or approval. Do not ask what the repository can answer or what can safely become a stated assumption.

All open questions must be answered before the plan can transition to READY FOR APPROVAL.

Do not combine unresolved clarifying questions and final approval in the same user prompt.

Plan State Lifecycle

Plan Status in the metadata block is the authoritative plan-level state. It is modelled once — there is no separate Approval field, because in the surveyed corpus the two contradicted each other in 11 of 32 plans.

1. DRAFT while creating the first version.
2. QUESTIONS PENDING while waiting for required clarification.
3. READY FOR APPROVAL after clarification is incorporated and the checker is clean.
4. APPROVED after the user approves execution.
5. IN PROGRESS while implementation is underway.
6. COMPLETED after cleanup, ## Pre-flight Checks and final verification all pass.

Use BLOCKED when planning or implementation cannot continue, and record the blocker.

Plan Format Rules

Every plan has these top-level sections, which is what check-plan.py E009 enforces:

Metadata, Status Legend, Context For A Clean Session, Goal, Scope, Non-Goals, Assumptions, Open Questions, Milestones (or Tasks in a simple plan), Project Gates, Pre-flight Checks, Decision Log, Final Verification, Approval Gate, Plan Self-Check, Execution Notes.

The metadata block is exactly four fields:

- Plan Status: DRAFT
- Plan Format: manual-planning v2.0.0
- Template: milestoned
- Tracking: untracked

Use exactly these task statuses: TO BE DONE, IN PROGRESS, COMPLETED, BLOCKED, SKIPPED.

Use exactly these plan statuses: DRAFT, QUESTIONS PENDING, READY FOR APPROVAL, APPROVED, IN PROGRESS, COMPLETED, BLOCKED.

A status may carry a trailing annotation (COMPLETED — 381/381 passing); the vocabulary applies to the leading token.

More than 10 tasks requires milestones. With 10 or fewer, omit milestones unless they clarify independent delivery phases.

## Project Gates is where project-specific rules live — per-project lint/build/test commands, manual-verification requirements, changelog or backlog bookkeeping. Put them there rather than forking this skill for a project.

## Pre-flight Checks is a named checklist of the project's actual commands, run before the plan may reach COMPLETED. It is distinct from per-task validation: per-task validation proves one task worked, pre-flight checks prove the repository is shippable.

Task Rules

Each task must include:

• Status: one of the task statuses.
• Depends On: none, or a list of task numbers.
• Objective: the observable outcome.
• Steps: concrete implementation steps.
• Validation: commands, tests, inspections, or self-checks that prove completion.
• Notes: constraints, affected files, or None.

Task numbering is not an execution order. Depends On is the order. Task 3.1 may be runnable before Task 2.2.

Prefer deterministic validation — a test, build, linter, or exact file inspection. Where none is possible, state the manual check in observable terms. Say explicitly when a validation passes by producing no output: grep finding nothing exits 1, and so does diff on files that are meant to differ. An executing agent that branches on $? will read those as failures.

Milestone Rules

Each milestone must include Status, Purpose, Exit Criteria, and its tasks. Exit criteria must be broader than any single task validation: they confirm the completed tasks work together and that the next milestone can safely start.

Implementation Workflow

1. Set the plan status to IN PROGRESS before starting implementation.
2. Before starting a task, set it to IN PROGRESS — plan-status.py <plan> set <id> "IN PROGRESS".
3. Complete the task.
4. Run the task validation. Before declaring it passed, check the task's Steps and Validation for explicitly named tests (e.g. "add a test test_foo_bar"). A green test suite does not mean those tests were written — verify by name.
5. Fix issues until validation passes, or mark the task BLOCKED with a reason.
6. Set the task to COMPLETED immediately after validation passes.
7. Update the milestone status when its tasks satisfy its exit criteria.
8. Start the next task only after the plan file reflects the current state.

If validation was intentionally deferred earlier, reconcile the plan text once the deferred checks actually run. Leave no stale "validation pending" phrasing describing a state the plan has moved past.

Discovered issues. If a bug or unplanned problem is identified while working on a task, choose one path immediately — do not defer via a mental note:

• Fix it in the current task if it is small and in scope.
• Create a new task in the plan with status BLOCKED if it is out of scope for the current task.

A bug that is noticed but neither fixed nor recorded will be forgotten. There is no third option.