writing-plans

name	writing-plans
description	Use when creating implementation plans, audit-remediation plans, agent handoff plans, issue plans, feature plans, refactor plans, or any APIVR Phase 2 plan that must be executable by another agent without placeholders. Requires exact file paths, test steps, evidence states, rollback criteria, and APIVR/Elite Build Goals alignment.
activation	Activate when the description trigger applies to the current task.
required_inputs	Task request, relevant repository context, constraints, and authority dependencies.
required_outputs	Skill-specific artifact, verification evidence, canonical verdict, and next action.
authority_dependencies	00_start_here/SOURCE_OF_TRUTH.md; 10_governance/APIVR_EXECUTION_LIFECYCLE.md; 10_governance/source_of_truth/Elite_Build_Goals_v3.md.
evidence_requirements	Executed checks or an honest Unknown, Not Run, or Blocked state for every material claim.

Writing Plans

Use this skill during APIVR Phase 2. A plan is acceptable only when a competent agent can execute it without inventing missing decisions.

Do not produce a vague plan. Do not use placeholders such as TBD, later, as needed, fix tests, update files, handle edge cases, clean up docs, wire things together, improve quality, or similar unsized work. If information is unknown, name the exact discovery step that will make it known.

Required Inputs

• APIVR tier and applicable Elite Build Goals.
• Objective, non-goals, acceptance criteria, and affected users/systems.
• Product premise, user/buyer, highest-risk assumption, success metric, and vertical slice when product strategy is involved.
• Canonical domain terms, states, events, and ADR requirements when durable vocabulary or decisions are involved.
• Exact files, commands, APIs, routes, schemas, assets, providers, jobs, or deployment surfaces in scope.
• Evidence required for each material claim.
• Rollback or restoration path for Standard and above.
• Compound-learning decision for Standard and above: what kind of outcome would update canonical guidance, create a solved-problem lesson, or require no durable learning.

Plan Structure

1. State APIVR tier and why that tier is sufficient.
2. List applicable Elite Build Goals and their effect on the plan.
3. Summarize current state from observed files or systems.
4. Define in scope, out of scope, preserved behavior, and smallest safe change.
5. Define domain glossary or ADR outputs when language or durable decisions affect the work.
6. Split large work into vertical, independently verifiable slices.
7. Run a pre-flight contradiction scan before execution: compare objective, non-goals, acceptance criteria, global constraints, tests, release gates, and task slices for conflicts or review-blocking instructions.
8. Write concrete implementation steps with exact file paths.
9. For code work, embed the failing test or test-case skeleton before production-code steps.
10. Add engineering plan review, code review, QA, release readiness, and DevEx review steps when applicable.
11. Add verification commands, manual checks, evidence states, and expected results.
12. Add rollback triggers and restoration steps.
13. Add compound-learning capture or knowledge-refresh decision for Standard and above work.
14. Add challenge-review questions for Important, Critical, Comprehensive, or Forensic work.
15. Apply skills/20-pass-protocol/SKILL.md before finalizing high-stakes, reusable, production-impacting, or agent-executed plans.

Decision Flow

Update the API handler and add tests. 1. Add failing test in `tests/billing/renewal.test.ts` named `renews annual plan without duplicate invoice`. 2. Run `npm test -- tests/billing/renewal.test.ts`; expected result: fails because duplicate invoice guard is missing. 3. Update `src/billing/renewal.ts` to check existing invoice by customer, plan, and billing period before creating a new one. 4. Re-run the same test; expected result: pass. 5. Run `npm test -- tests/billing/renewal.test.ts tests/billing/webhook.test.ts`; expected result: pass.