planning

# Planning & Orchestration This skill helps you transform an ambiguous or messy situation into a **small-steps execution plan** with clear verification criteria, aligned with the repository's conventions. ## When to Use **✅ DO Use:** - When the user asks for a plan/strategy instead of code - When requirements are unclear or the scope is large - When you need to sequence tasks (tests → refactor → security → docs) - When coordinating multiple subagents (testing, refactor, security, documentation) - When you must preserve constraints (architecture rules, contracts, dependencies) **❌ DON'T Use:** - Trivial tasks with 1–2 obvious steps - When the user explicitly asked for implementation right now (skip planning and implement) - When you already have a validated plan and only need execution ## Core Concepts ### 1) Constraints First Capture non-negotiables before proposing steps: - Tech stack/runtime constraints (Node/TS, frameworks) - Architecture rules (layer boundaries, repositories required, etc.) - Contract-first requirements (OpenAPI, runtime validation) - Observability/security baselines (logging, correlation id, rate limit, helmet) ### 2) Incremental Delivery (Micro-iterations) Prefer **small, verifiable increments** over big-bang rewrites. Each iteration should have: - A single goal - Minimal change set - A verification step (tests, lint, manual smoke check) - A clear rollback story (what to revert if it fails) ### 3) Verification Is Part of the Plan Every planned step must have at least one verification method: - **Automated**: unit/integration tests, contract validation, linting - **Manual**: curl/Postman checks for a narrow endpoint behavior - **Safety**: ensure sensitive fields (e.g., passwords) never leak ## Planning Patterns ### Pattern 1: Situation Snapshot In 5–10 lines, summarize: - What exists today (endpoints, modules, structure) - What is broken/risky (security holes, missing validation, lack of tests) - What must not change (API contract, core behavior, compatibility) ### Pattern 2: Gap-to-Goal Mapping List goals and map each to a concrete deliverable: - **Tests** → test files + scenarios + data builders + how to run - **Architecture** → target folder structure + boundaries + dependency injection approach - **Security** → middleware + validation + secrets/token strategy + error handling ### Pattern 3: Micro-Iteration Plan (Ralph Loop) Produce steps as **small loops**: - Goal - Changes (specific files/modules) - Risks - Verification - Next-step prompt (optional) to delegate to a specialist subagent ### Pattern 4: “Next Prompts” (Delegation) When appropriate, propose copy-pastable prompts to delegate execution: - `/agt-dev-test` for tests - `/agt-dev-refactor` for layering/refactors - `/agt-dev-security` for hardening ## Output Template When delivering a plan, use this structure: 1. **Summary** 2. **Constraints & Assumptions** 3. **Current Risks / Findings** 4. **Plan (small steps)**: - Step name - Goal - Changes (files/modules) - Verification 5. **Suggested Next Prompts** (optional, copy/paste) ## Key Principles 1. **Small steps beat perfect steps** 2. **Name files and verification explicitly** 3. **Respect architecture boundaries and contracts** 4. **Security and observability are not “later”**