Repo-grounded Change

What does Repo-grounded Change do?

Turn an optimization request for an existing project into a confirmed, implementation-ready change and then execute only the approved option.

Interaction and authorization contract

• Inspect the current repository before recommending a solution. Do not ask the user for facts discoverable from code, tests, configuration, or applicable product documents.
• Remain read-only until the user explicitly approves an option or modification baseline. Diagnostics and repository inspection do not authorize edits.
• Do not force this workflow onto a direct, unambiguous implementation request. Use the gate when the user asks for evaluation first or when a choice materially affects behavior, compatibility, risk, or scope.
• Ask only decision-bearing questions. Use a structured user-input control when available; otherwise use concise option codes such as Q1-A.
• Normally provide 2 or 3 mutually exclusive feasible options. Put the recommended option first and explain why. If only one safe option exists, explain why the alternatives were rejected instead of inventing fake choices.
• After confirmation, implement the selected option without silently adding unrelated cleanup. If new repository facts would materially change the approved behavior, scope, migration, dependency, or acceptance criteria, stop and ask for a revised decision.

Evidence and decision labels

Keep facts separate from interpretation:

• User goal: the pain point and outcome stated by the user.
• Code fact: behavior observed in current source, tests, runtime, or configuration.
• Document fact: behavior required by the applicable approved product document.
• Technical suggestion: an implementation recommendation that preserves the intended product behavior.
• Product assumption: a reversible assumption that requires confirmation.
• Pending confirmation: an unresolved choice that prevents implementation.
• Confirmed: the option or baseline explicitly approved by the user.
• Not changed this time: behavior or code intentionally outside the approved change.

Unless the user specifies otherwise, use this authority order:

1. Current explicit user instructions.
2. Decisions explicitly confirmed in the current task.
3. The applicable approved product specification.
4. Current code and tests for existing behavior.
5. README files and historical documents.

Expose conflicts; do not silently choose one source.

Workflow

1. Discover the current behavior

Read references/discovery-and-impact.md. Inspect only the repository areas needed to reproduce or explain the pain point. Protect existing user changes and establish the current test baseline when proportionate.

Report the current behavior, user impact, relevant code boundaries, and missing evidence before presenting the options.

2. Clarify the change objective

Translate the request into observable outcomes and constraints. Clarify only issues that can change the option, scope, compatibility strategy, or acceptance result.

Do not treat literal UI wording as a required implementation mechanism when it would introduce incorrect interaction semantics. Explain the distinction and offer a repository-compatible option.

3. Compare feasible options

Read references/options-and-clarification.md. Compare product and engineering impact, including user experience, preserved behavior, state and data compatibility, accessibility, test impact, implementation effort, rollback difficulty, and meaningful risks.

4. Produce the recommended change specification

Read references/change-spec-and-acceptance.md. The recommended option must be directly executable by Codex and include:

• target behavior and interaction;
• affected modules, components, files, interfaces, and state;
• compatibility, persistence, migration, degradation, and rollback handling where relevant;
• behavior and data that must be preserved;
• explicit exclusions;
• test plan and observable acceptance criteria.

Do not modify code in this step.

5. Obtain explicit approval

Present the recommendation and remaining choices. Stop after asking the user to select an option or answer the smallest necessary clarification round.

After the response, summarize the confirmed option, user modifications, unresolved matters, downstream impacts, and final acceptance baseline. Begin implementation only when the response clearly authorizes execution, such as Confirm Option A or Execute as recommended.

6. Implement the approved option

Recheck the dirty worktree, preserve unrelated changes, and make the smallest coherent implementation. Comments should explain non-obvious invariants or compatibility decisions, not restate the code.

Do not delete underlying domain data merely because its UI presentation is removed unless deletion was explicitly approved. When changing persisted states, routes, schemas, or enums, handle legacy values when the repository indicates they may exist.

7. Verify and report

Run focused tests first, then proportionate repository-wide checks such as type checking, lint, full tests, build, and UI interaction or visual verification. Do not claim a check passed if it could not run.

Report the implemented outcome, main files, verification evidence, known limitations, and any unrelated pre-existing warnings. If a requested validation surface is unavailable, disclose it and do not bypass an explicitly selected tool or environment without approval.

Mandatory stop conditions

Stop and request a decision when:

• two feasible options produce materially different user behavior;
• implementation requires an unapproved dependency, integration, credential, migration, destructive action, or business-rule change;
• current user changes overlap the required edit and cannot be preserved safely;
• repository facts contradict the approved option;
• acceptance criteria cannot be made observable;
• completing the change safely would require expanding the approved scope.

Difficulty, duration, or ordinary implementation details are not reasons to reopen a confirmed decision.

Completion standard

The workflow is complete only when the selected option is implemented within scope, compatibility decisions are handled, acceptance criteria map to observable evidence, relevant checks have run, and limitations are reported honestly.