01-Yang/codebase-convergence

Codebase Convergence

Make a repository easier to understand and change without redesigning it. Prefer evidence, a small interface, and local fixes over speculative abstractions.

Guardrails

• State the scope, assumptions, protected content, and success checks before a multi-step change.
• Read repository instructions, the domain glossary, and relevant ADRs before judging architecture. Use the repository's domain names.
• Touch only files that serve the request. Preserve unrelated user changes and remove only imports, code, or docs made obsolete by this work.
• Treat explicitly protected domain text, titles, data definitions, and user-designated copy as locked. Keep it verbatim. If its status is unclear, include it in the decision packet instead of editing it.
• Do not change a numerical value or its representation—configuration, threshold, balance, rate, limit, or documented value—without explicit approval.
• Do not silently change a business rule, state transition, interaction behavior, public interface, or visual contract. Treat it as a decision unless the fix is directly implied and behavior-preserving.
• Keep one source of truth for each fact. Do not create documentation that merely repeats another document.

Workflow

1. Establish the baseline

1. Inspect the worktree and identify only the requested area. Note unrelated modifications; do not stage or alter them.
2. Map the relevant code paths, state/data ownership, UI flow, tests, and Markdown files. Read the documents that currently define the domain and decisions before files that implement them.
3. Record each finding with evidence: files, conflicting statements or paths, user impact, and whether it is safe to resolve directly.
4. Classify findings:
   • Direct convergence: duplication, stale links, contradictory non-locked prose, or a localized implementation/UI defect with a behavior-preserving fix.
   • Decision required: any numerical value, rule, behavior, protected content, public interface, or ambiguous source of truth.
   • Architecture candidate: a potentially deeper module or a change whose seam is not yet agreed.

2. Ask once for material decisions

Complete discovery before asking questions. Send one decision packet containing every unresolved item; do not drip questions across turns.

For each numerical item, include its identifier and files, current values, evidence of the inconsistency, impact, and a recommendation or clearly say that no value is being proposed. Do not edit, normalize, move, or remove the affected numerical expression until the user explicitly approves it.

Include other material uncertainties in the same packet: locked-content status, behavior choices, ownership conflicts, and architecture choices. Continue with independent direct convergence while approval is pending.

3. Apply direct convergence

Keep each change surgical and traceable to a finding.

Documentation

• Give each document one responsibility. Respect existing conventions; otherwise keep the minimum set: entry-point overview, architecture/system map, domain or product rules, decisions, and current work/status.
• Merge overlapping PRDs, plans, and work logs by retaining the authoritative content once. Move durable rationale to the project's decision records and keep operational status short.
• Preserve locked blocks verbatim when relocating them. If a merge would alter a locked block or a numerical expression, leave that hunk for approval.
• Remove repetition, stale references, and conflicting non-locked explanations. Update links after moves and avoid summary documents that duplicate specifications.

Code and UI

• Trace a user action through state ownership to the rendered result before editing UI code.
• Fix concrete inconsistency: duplicated presentation state, mismatched event/data names, invalid conditional flow, dead code created by this change, or a component responsibility that blocks a local fix.
• Keep layout, interaction, accessibility, and responsive behavior stable unless the user approves a product or visual change.
• Prefer one clear owner of a state transition and one canonical representation of data. Do not introduce abstraction, configuration, or error handling without a demonstrated need.

4. Evaluate architecture candidates separately

Use these terms consistently:

• Module: a unit with an interface and implementation.
• Interface: everything callers must know, including invariants and error modes.
• Seam: where behavior can change without editing callers.
• Depth: leverage from substantial behavior behind a small interface; locality: related knowledge and change stay together.

Apply the deletion test: if deleting a module merely moves its complexity into callers, it earns its keep; if complexity vanishes, it is likely shallow. Do not create a seam for one adapter alone.

For a candidate that changes an interface, behavior, or ownership, do not implement it immediately. Create a concise self-contained HTML report in the OS temporary directory only when a visual comparison will help. Include files, evidence, before/after diagram, expected locality and leverage, ADR conflict if any, and recommendation strength. Ask the user to choose a candidate before designing the interface.

5. Verify and hand off

1. Inspect the final diff for scope, locked-content preservation, duplicate sources of truth, and unintended value or behavior changes.
2. Run the relevant existing formatter, lint, type check, tests, build, and UI verification. Do not add tools or broad test suites solely for this task. Distinguish pre-existing failures from introduced ones.
3. Confirm Markdown links and headings after consolidation and verify each changed statement against its canonical source.
4. Report direct changes, unresolved decision items, verification results, and risks in concise terms. Every changed line must trace to the requested convergence.