Gather Context

Research a codebase before touching it. Parallel research -> synthesis -> 3 ranked approaches -> wait for approval.

Primary goal for open source: Changes must look like the maintainer wrote them. Minimal diff. Maximum style alignment.

Phase 0 — Issue Intake

Before research, frame the task from the issue/request itself.

• Restate the issue in plain language
• Extract explicit acceptance criteria
• Mark assumptions and missing product decisions
• Classify the task: bug | feature | refactor | claim-check

If the issue is underspecified in a way that would materially change the implementation, stop here and ask 1-3 targeted questions instead of forcing options.

Phase 1 — Define Target Scenario, Then Launch 4 Voyager Agents in Parallel

Before launching subagents, generate exactly 1 Gherkin scenario from the original user query. Keep it minimal and targeted. We are defining the smallest user-visible contract for a simple enhancement, not a full spec.

Use this format:

Scenario: [User action and outcome]

Given [user state/precondition] When [user action] Then [user-visible outcome with verifiable condition]

Acceptance Criteria:

• [Measurable outcome: specific value/threshold/state]

Rules:

• Generate exactly 1 scenario
• Base it on the original user query, not on implementation guesses
• Keep it user-visible, testable, falsifiable, and implementation-agnostic
• Keep it minimal and targeted to the enhancement being requested
• This scenario is the target goal for all subagents

Spawn all four simultaneously using the Task tool with subagent_type: voyager.

Pass the scenario to every subagent as part of its task context so research stays anchored to the same target behavior.

Evidence requirement: All agents must cite findings with code snippets, file paths, and line numbers. No assertions without evidence. If results are thin or inconclusive, note gaps explicitly in Phase 2 — do not proceed with assumptions.

Agent 1: Code Archaeology

What does this code do today, and how?

• Locate entry points, relevant files, core logic
• Trace the current implementation end-to-end
• Identify existing tests covering this area
• Note any TODOs, FIXMEs, or known issues near the target

Agent 2: Dependency Map

What breaks if we touch this?

• Map callers and callback/event consumers (what depends on this code, including who reacts to emitted/invoked behavior)
• Map callees and callback/event producers (what this code depends on, including what it emits/invokes)
• Capture invocation cardinality and order for critical interactions (once vs multiple, before vs after)
• Identify public API surface vs internal details
• Assess blast radius: files, modules, tests, and cross-component behavioral side effects at risk
• Flag any breaking change risks

Agent 3: UX Behavior

What does the user see today, and what will they see after?

Given the feature/change being investigated, trace the user-facing path — not the code path.

• Current UX — step by step what the user sees and can do today (screens, states, limits, caps, hidden elements)
• Post-change UX — same walkthrough after the proposed change; explicitly call out anything that stays blocked, hidden, or broken

The main agent must tell this agent what feature is being added/changed so it can focus the trace. Output must be two clearly labelled sections: Current UX and Post-change UX. No prose beyond what is needed to describe user-visible behavior. Flag any gap where the post-change UX does not match user expectations.

Agent 4: Style Fingerprint

How does this codebase write code?

Start with files adjacent to the task. Expand repo-wide when touching shared infrastructure.

Look for:

• Naming conventions (variables, functions, types, files)
• Error handling patterns (exceptions vs return values vs Result types)
• How similar problems are solved elsewhere in the codebase
• Test structure and naming
• Code organization within files (imports, grouping, ordering)
• Linting/formatting config (.eslintrc, pyproject.toml, .editorconfig, etc.)
• Commit/PR style if relevant (small focused changes vs large PRs)

Output: A concise style cheatsheet — bullet points only, no prose.

Phase 2 — Synthesize

After all 4 agents return, combine findings:

1. Original scenario — the single target scenario from Phase 1, surfaced verbatim
2. Current UX — what the user sees and can do today (from Agent 3, surfaced here verbatim)
3. Post-change UX — what the user will see after the change (from Agent 3, surfaced here verbatim)
4. Current behavior — what the code does today
5. Constraints — what must not change (public API, test contracts, style rules)
6. Style rules — the extracted cheatsheet from Agent 4
7. Blast radius — scope of impact from Agent 2

Decision Heuristics (Apply to every proposal)

Use these as hard filters before presenting options:

1. Reuse first (DRY): prefer existing modules/components/patterns over new ones.

2. KISS: choose the least complex approach that meets requirements.

3. YAGNI: do not add extensibility/abstractions unless current requirement needs it.

4. Single source of truth: avoid duplicated state/data paths.

5. User trust/safety: no risky shortcuts that could create silent bad outcomes.

6. Original scenario — the single target scenario from Phase 1, surfaced verbatim

7. Current UX — what the user sees and can do today (from Agent 3, surfaced here verbatim)

8. Post-change UX — what the user will see after the change (from Agent 3, surfaced here verbatim)

9. Current behavior — what the code does today

10. Constraints — what must not change (public API, test contracts, style rules)

11. Style rules — the extracted cheatsheet from Agent 4

12. Blast radius — scope of impact from Agent 2

Phase 3 — Present 3 Approaches

Use references/approach-template.md for consistent output format.

Rank by: minimal diff + style alignment first -> more involved last.

Each option must include one regression probe describing how to verify no duplicate trigger/clobber regressions were introduced.

For each option ask: "Would a maintainer approve this PR without asking for changes?"

Reason from first principles: work backwards from the goal — what is the simplest change that satisfies the requirement without introducing concepts the codebase doesn't already use?

After the user selects an option, emit a workflow handoff packet with:

• Chosen approach
• Implementation steps
• Verification steps
• PR summary bullets
• Files likely to change
• Tests to add/update
• Risks / rollback notes
• Commit/PR summary draft

Phase 4 — Hard Stop

Present the 3 options and wait for explicit user selection.

Do not begin implementation until the user picks an approach.