Plan work

Goal

Produce a plan that is: - grounded in repo reality (research) - explicit about decisions and risks (analysis) - blocked on zero unknowns (Q&A before implementation steps)

Inputs to ask for (if missing)

• Outcome/acceptance criteria (what "done" means).
• Constraints: time, backwards compatibility, performance, security, data migration.
• Target environment(s): local/stage/prod; any feature flags or rollout requirements.
• Non-goals (what not to do).

Workflow (research -> analysis -> Q&A -> implementation)

1) Research (current state) - Read repo guidance first: AGENTS.md, README.md, docs/ (only if needed). - Identify entrypoints and owners (backend/frontend/infra). - Find relevant code paths and patterns: - rg for symbols, endpoints, config keys, error strings - git log -p / git blame for history and intent when uncertain - If the plan depends on external behavior (framework/library/tooling), consult official docs, release notes or context7 (and call out versions/assumptions). - Capture findings as short bullets with file paths. 2) Analysis (what to change and why) - Restate requirements and assumptions. - List options (1-3) with tradeoffs; pick one and justify. - Identify risks/edge cases and what tests cover them. - Collect open questions. 3) Q&A gate (do not skip) - If there are open questions, ask them and stop. - Do not propose implementation steps until the user answers (or explicitly accepts assumptions). - First pass: ask 1-5 questions that eliminate whole branches of work. - Do not limit yourself to just 1-5 questions overall; continue asking until everything needed for a proper implementation plan is clarified. - Make questions scannable: numbered, short, multiple-choice when possible. - Include defaults/recommendations and a fast-path response (e.g., reply "defaults"). - Do not label any option as the default within the option list; if needed, state defaults in a separate note. - Provide a low-friction "not sure" option when helpful. - You may add brief bracketed insights after options when there's a major upside or downside. - Separate "Need to know" from "Nice to know" when it reduces friction. - Structure options for compact replies (e.g., "1b 2a 3c") and restate selections in plain language. - Pause before acting until must-have answers arrive: - Do not run commands, edit files, or produce a plan that depends on unknowns. - Low-risk discovery is allowed if it does not commit to a direction (read-only, non-committing). - After answers, restate requirements in 1-3 sentences (constraints + success criteria), then proceed. 4) Implementation plan (only after Q&A) - Break into small steps in a sensible order. - Name likely files/dirs to change. - Include the tests to run (unit/integration/build) to validate the change.
- If the change spans modules, include coordination steps (contract changes, client regen, versioning).

Q&A template (short, feature plan)

Before I start, I need: (1) question (2) question (3) question. This is a starting set; I will continue with follow-up questions until everything needed for a proper implementation plan is clarified.

Need to know 1) a) b) c) 2) a) b) c) 3) C a) b) c) d)

Nice to know 4) a) b) c)

Reply with: "1a 2b 3c 4a" (or "propose" to have me choose and confirm).

Deliverable

Use references/plan-template.md and fill it in.