write-plan

Write Plan

Write a rigorous implementation plan assuming the engineer has zero context about the codebase and will execute tasks in isolation. Every step must contain everything they need — no references to "fill in later", no vague instructions, no placeholders.

DRY. YAGNI. TDD. Frequent commits. Focus on clear contracts, behavioral specs, and independent verification rather than premature code dumps. Prefer designs that are easy to explain, reason about locally, and change.

GitHub body safety — mandatory

Never place a Markdown plan in a shell-quoted gh --body argument. Backticks, $, and command examples in Markdown are shell syntax inside double-quoted Bash strings and can execute commands or leak their output into GitHub.

Write every issue body/comment to a temporary Markdown file outside the repository with the file-writing tool, then pass it with --body-file. Never use --body "...", --body "$(...)", backticks in a shell string, or an unquoted heredoc. If a heredoc is unavoidable, use a single-quoted delimiter: <<'EOF'.

After publication, verify that GitHub stored literal Markdown. If shell output or credentials appear, immediately delete/replace the affected comment, stop work, and tell the user to rotate exposed credentials.

Scope Check

Before investigation, state the proposed scope in three short bullets:

• Required outcome: the behavior explicitly requested by the issue or spec.
• Non-goals: adjacent features, refactors, generalization, cleanup, and future-proofing that are not required for that outcome.
• Simplest likely approach: the smallest change expected to deliver the required outcome, using existing patterns where possible.

Treat the issue or spec as a strict boundary. Every task, changed file, dependency, test, and design decision must map to an explicit requirement or a demonstrated correctness need. Do not infer new product requirements or add infrastructure, abstractions, migrations, or extra capabilities merely because they may be useful later. Record relevant ideas that are not necessary under Out of scope rather than adding them to the plan.