Plan Code Changes
Turn a change request into an implementation-ready brief before editing code. Ask targeted follow-up questions only for decisions that are unresolved or that would materially change the implementation.
If the request is ambiguous at the problem-definition level, do not try to plan around that ambiguity. Use ask-user-question first to resolve the user's actual goal, then resume this skill once the intended change is clear.
Workflow
- Restate the request in 2-4 sentences.
Include current assumptions, inferred scope, and why clarification is needed.
If the core request still has multiple plausible interpretations, stop and use
ask-user-question.
- Inspect local context before asking questions.
Prefer fast repository inspection first: directory layout, adjacent code, tests, CI config, docs, and style/tooling files.
If the target repository or path is unclear, ask for it before asking deeper implementation questions.
- Decide whether questions are actually needed.
If the request and repository already answer a category, do not ask about it.
- Ask 1-6 focused questions in a single round.
Group related items together. Prefer concrete options when helpful, but allow free-text answers.
- After the answers arrive, produce a short implementation brief.
Include the requested outcome, likely touchpoints, chosen approach, tests, CI or tooling changes, documentation updates, and remaining risks.
- If something still blocks implementation, ask only the minimal follow-up.
If the request is already well-specified after the context scan, skip the question round and produce the implementation brief immediately instead of inventing questions.
Question Coverage
Always consider these categories. Ask about them only when they are relevant and still unresolved.
- Behavior and scope: exact user-visible behavior, acceptance criteria, and excluded scope.
- Repository target and touchpoints: which repo, service, package, directory, or entrypoint should change.
- Interfaces and contracts: APIs, events, schemas, env vars, CLI flags, and backward compatibility.
- Data and migrations: persistence changes, migrations, backfills, defaults, cleanup, and rollout safety.
- Directory structure and ownership: where new files belong, package or module boundaries, naming, and whether to extend existing code or add a new abstraction.
- Implementation constraints: dependency choices, framework or language version, performance, security, accessibility, localization, and observability.
- Tests: unit, integration, end-to-end, fixtures, mocks, regression coverage, and failure cases.
- CI and tooling: lint, typecheck, test, build, release, matrix changes, generated files, secrets, and permissions.
- Documentation and release notes: README updates, inline docs, examples, changelog, migration notes, and operator guidance.
- Code style and conventions: typing strictness, error handling, logging, naming, comments, and repository-specific patterns to follow.
- Rollout and operations: feature flags, staged rollout, monitoring, alerts, and rollback expectations.
Question Design Rules
- Ask the minimum set of questions that will change the plan.
- Prefer repository-specific questions over generic ones.
- Combine related categories into one question when that reduces churn.
- State obvious defaults when they come from the repository, and invite correction instead of forcing a choice.
- Treat user-stated preferences as settled unless they conflict with the repository.
- When the user says to choose, pick the option that best matches existing patterns and record the assumption in the brief.
- Avoid broad brainstorming questions when a narrower implementation choice is what matters.
Output Shape
When clarification is needed, respond in this order:
Current Understanding
Summarize the requested change, the affected area, and the main assumptions.
Questions
Ask a concise numbered list. Each question should be actionable and tied to an implementation decision.
Draft Plan
Include a provisional plan so the user can react to the direction, not just the questions. Keep it short and concrete.
Planning Brief
After the user answers, provide a compact implementation brief with these headings:
- Scope
- Code touchpoints
- Implementation approach
- Test plan
- CI or tooling changes
- Documentation changes
- Risks or follow-ups
Keep the brief specific enough that implementation can start immediately afterward.
1---2name: plan-code-changes3description: Planning and clarification workflow for requested code changes. Use when a user describes a new feature, bug fix, refactor, migration, integration, UI change, API change, test change, CI/CD change, or other code alteration and Codex should pause before implementation to clarify scope, behavior, affected files, implementation constraints, testing, CI, documentation, code style, directory placement, rollout, and acceptance criteria. Use this after the overall request is clear enough to plan; if the user's actual goal or intended outcome is still ambiguous, `ask-user-question` should trigger first.4---56# Plan Code Changes78Turn a change request into an implementation-ready brief before editing code. Ask targeted follow-up questions only for decisions that are unresolved or that would materially change the implementation.910If the request is ambiguous at the problem-definition level, do not try to plan around that ambiguity. Use `ask-user-question` first to resolve the user's actual goal, then resume this skill once the intended change is clear.1112## Workflow13141. Restate the request in 2-4 sentences.15 Include current assumptions, inferred scope, and why clarification is needed.16 If the core request still has multiple plausible interpretations, stop and use `ask-user-question`.172. Inspect local context before asking questions.18 Prefer fast repository inspection first: directory layout, adjacent code, tests, CI config, docs, and style/tooling files.19 If the target repository or path is unclear, ask for it before asking deeper implementation questions.203. Decide whether questions are actually needed.21 If the request and repository already answer a category, do not ask about it.224. Ask 1-6 focused questions in a single round.23 Group related items together. Prefer concrete options when helpful, but allow free-text answers.245. After the answers arrive, produce a short implementation brief.25 Include the requested outcome, likely touchpoints, chosen approach, tests, CI or tooling changes, documentation updates, and remaining risks.266. If something still blocks implementation, ask only the minimal follow-up.2728If the request is already well-specified after the context scan, skip the question round and produce the implementation brief immediately instead of inventing questions.2930## Question Coverage3132Always consider these categories. Ask about them only when they are relevant and still unresolved.3334- Behavior and scope: exact user-visible behavior, acceptance criteria, and excluded scope.35- Repository target and touchpoints: which repo, service, package, directory, or entrypoint should change.36- Interfaces and contracts: APIs, events, schemas, env vars, CLI flags, and backward compatibility.37- Data and migrations: persistence changes, migrations, backfills, defaults, cleanup, and rollout safety.38- Directory structure and ownership: where new files belong, package or module boundaries, naming, and whether to extend existing code or add a new abstraction.39- Implementation constraints: dependency choices, framework or language version, performance, security, accessibility, localization, and observability.40- Tests: unit, integration, end-to-end, fixtures, mocks, regression coverage, and failure cases.41- CI and tooling: lint, typecheck, test, build, release, matrix changes, generated files, secrets, and permissions.42- Documentation and release notes: README updates, inline docs, examples, changelog, migration notes, and operator guidance.43- Code style and conventions: typing strictness, error handling, logging, naming, comments, and repository-specific patterns to follow.44- Rollout and operations: feature flags, staged rollout, monitoring, alerts, and rollback expectations.4546## Question Design Rules4748- Ask the minimum set of questions that will change the plan.49- Prefer repository-specific questions over generic ones.50- Combine related categories into one question when that reduces churn.51- State obvious defaults when they come from the repository, and invite correction instead of forcing a choice.52- Treat user-stated preferences as settled unless they conflict with the repository.53- When the user says to choose, pick the option that best matches existing patterns and record the assumption in the brief.54- Avoid broad brainstorming questions when a narrower implementation choice is what matters.5556## Output Shape5758When clarification is needed, respond in this order:5960### Current Understanding6162Summarize the requested change, the affected area, and the main assumptions.6364### Questions6566Ask a concise numbered list. Each question should be actionable and tied to an implementation decision.6768### Draft Plan6970Include a provisional plan so the user can react to the direction, not just the questions. Keep it short and concrete.7172## Planning Brief7374After the user answers, provide a compact implementation brief with these headings:7576- Scope77- Code touchpoints78- Implementation approach79- Test plan80- CI or tooling changes81- Documentation changes82- Risks or follow-ups8384Keep the brief specific enough that implementation can start immediately afterward.
LegendaryLinux