Produce a *.plan.md with exactly these 13 sections in order:
1. Goal
State the single concrete outcome this change achieves. One or two sentences.
2. Non-goals
List at least 3 items stating what this change will NOT do. Examples: no full module refactor, no CLI change, no new external dependency, no performance work.
3. Current Context
Briefly describe the relevant existing code, module, or system state. Name the files, classes, or functions that provide context for the change.
4. Requirements
List measurable requirements. Each item must be verifiable in tests or validation output.
5. Decisions
Record the async-routing decision plus answers to all 7 standard decision points before drafting the rest of the plan:
- Async-planning status:
triggered or exempt, with cited repo-visible trigger or exemption evidence
- Module/package placement: which module or package receives the new code
- New public API: yes/no — name and signature if yes
- Interface changes: yes/no — which interfaces and how
- Breaking changes allowed: yes/no — reason if yes
- New dependencies: yes/no — name and version if yes
- Error handling strategy: which exceptions are raised and when
- Typing strategy: fully typed, use of
Any, use of TypeVar or Protocol, etc.
When Async-planning status is triggered, the plan artifact must append these exact subsections under ## Decisions in this exact order:
### Async boundary decision### Resource lifecycle decision### Concurrency model### Failure model### Cancellation / timeout policy### Validation plan### Handoff notes for the implementer
When the status is exempt, keep the Async-planning status line and its exemption citation in ## Decisions; do not leave exemption reasoning implicit anywhere else.
If request, baseline, or review notes conflict on async applicability or on an async decision, add ### Async contradiction log rather than smoothing the conflict over. If the contradiction is discovered in an already-started plan, treat the repair as retrofit required.
6. Public Contract / API Changes
Describe new or changed public functions, classes, or methods. Include signatures, parameters, return types, exceptions, and backward compatibility notes. If no public API changes, state explicitly.
7. Affected Files / Modules
Use the following format:
Likely affected files:
- src/xxx/yyy.py
- tests/test_yyy.py
Candidate files to inspect:
- src/...
8. Implementation Steps
Numbered, executable steps with explicit file references. Each step names a specific file and a specific action. NOT: "Refactor the validation module." YES: "1. Open src/utils/validation.py. Add validate_email(email: str) -> bool below existing validators."
9. Test Plan
Must be specific. Name the test file and cover all of the following categories:
- Happy path
- Invalid input
- Edge case
- Regression
- Backward compatibility
For async-capable topics, make the test plan and validation plan consistent with the async-planning subsections. If cancellation, timeout, grouped failure, or resource cleanup are part of the async baseline, name them explicitly here.
10. Validation Commands
Either explicit commands:
pytest tests/test_xxx.py -v
mypy src/xxx/yyy.py
ruff check src/
Or reference the project config:
Use existing project validation commands from pyproject.toml / Makefile / README.
11. Risks
Name at least one concrete risk. Examples: "may affect existing public API callers", "adds a regex that could introduce import-time cost", "type annotation changes may break downstream stubs".
12. Rollback Plan
State how to undo the change. At minimum: name the changed files and how to revert them (e.g., "revert via git: src/xxx/yyy.py, tests/test_yyy.py").
13. Open Questions
List unresolved questions and who can answer them. State "None" if all questions are resolved.
