/scope — Parallel Change-Scope Analyzer

Analyze a requirement and produce a change-scope report by running multiple analysis agents in parallel. Two rounds of concurrent execution, then synthesis.

The whole point is speed: instead of sequential analysis that takes 5 minutes, launch everything at once and get results in ~1 minute.

Input

The user provides a requirement, bug description, or feature request. Examples:

"I want to refactor the hook system"
"Add auto-fix feature to the check skill"
"spec.json validation is too slow"

If the requirement is too vague to search for (e.g., "improve things"), ask ONE clarifying question. Otherwise, proceed immediately.

Phase 1: State Discovery

Two steps: first parallel agents, then /check skill.

Step 1A: Parallel Agents (3 concurrent)

Launch all three agents in a single message so they run concurrently.

Agent 1: code-explorer

Find all code directly related to the requirement.

Prompt template:
"Find all code related to: {requirement}
Focus on: entry points, core logic, data flow, and test files.
Project root: {project_root}"

Agent 2: docs-researcher

Find internal documentation, ADRs, and conventions relevant to the change.

Prompt template:
"Find internal documentation relevant to: {requirement}
Look for: architecture decisions, conventions, constraints, related past changes.
Project root: {project_root}"

Agent 3: code-explorer (git state)

Understand current git state and recent changes in the affected area.

Prompt template:
"Analyze the current git state for areas related to: {requirement}
1. Run: git log --oneline -10 for recent changes in relevant areas
2. Run: git diff --name-only to find uncommitted changes
3. Identify any in-progress work that might interact
Project root: {project_root}"

Implementation: Use three parallel Agent tool calls with subagent_type set to code-explorer for Agents 1 and 3, and docs-researcher for Agent 2.

Step 1B: /check Skill

After the three parallel agents complete, invoke the /check skill via Skill tool. This runs the full rule-based verification against .hoyeon/rules/ to surface any cascading change requirements or rule violations in the affected area.

Skill("check")

Wait for /check to complete. Its PASS/WARN results feed into Phase 2 as check_results.

Skip condition: If .hoyeon/rules/ does not exist, skip Step 1B and proceed directly to Phase 2 (note "no rules configured" in the report).

Phase 2: Deep Analysis (Parallel)

After Phase 1 (Step 1A + 1B) completes, launch three more agents in a single message. Inject Phase 1 findings as context into each prompt.

Agent 4: gap-analyzer

Prompt template:
"Analyze gaps for this change:

Requirement: {requirement}

Code findings:
{agent_1_results}

Documentation findings:
{agent_2_results}

Current state:
{agent_3_results}

Check results (rule violations/warnings):
{check_results}

Focus on: missing requirements, edge cases, things that must NOT be changed."

Agent 5: tradeoff-analyzer

Prompt template:
"Analyze tradeoffs for this change:

Requirement: {requirement}

Code findings:
{agent_1_results}

Focus on: risk per file/module, simpler alternatives, over-engineering warnings.
Skip decision_point YAML — just give the risk table and alternatives."

Agent 6: codex-strategist

Prompt template:
"Synthesize a strategic view of this change:

Requirement: {requirement}

Code findings:
{agent_1_results}

Documentation context:
{agent_2_results}

Gap analysis:
{agent_4_results — if available, otherwise pass Phase 1 summary}

Focus on: blind spots, cross-cutting concerns, architectural fit."

Note on Phase 2 ordering: Agents 4, 5, and 6 can all launch together because they each receive Phase 1 results directly. Agent 6 (codex-strategist) works with Phase 1 results — it does not need to wait for Agent 4's output. The codex-strategist provides independent strategic synthesis, not a review of the gap analysis.

Phase 3: Synthesis

After all agents complete, synthesize results into a single report. Do this yourself — no subagent needed.

Output Format

## Scope Analysis: {requirement_title}

### 1. Change Map
| File/Module | Change Type | Risk | Reason |
|-------------|-------------|------|--------|
| path/to/file.ts | MODIFY | LOW | {why} |
| path/to/other.ts | MODIFY | HIGH | {why} |
| path/to/new.ts | CREATE | MED | {why} |

### 2. Impact Radius
- **Direct**: {files that must change}
- **Indirect**: {files that might need adjustment}
- **Tests**: {test files to update/create}
- **Docs**: {documentation to update}

### 3. Risk Summary
| Risk | Count | Key Items |
|------|-------|-----------|
| HIGH | N | {list} |
| MED | N | {list} |
| LOW | N | {list} |

### 4. Gaps & Warnings
- {gap or warning from gap-analyzer}
- {over-engineering warning from tradeoff-analyzer}
- {blind spot from codex-strategist}

### 5. Recommended Approach
{1-3 sentences: the simplest path to implement this change}

**Suggested order**:
1. {first thing to do}
2. {second thing to do}
3. {third thing to do}

### 6. Must NOT Do
- {prohibition from gap-analyzer}
- {prohibition from tradeoff-analyzer}

Output Rules

Every file path must be absolute or repo-relative (no vague references)
Risk levels must be justified (not arbitrary)
Keep the report under 80 lines — brevity is the point
If any agent returned DEGRADED/SKIPPED, note it but don't block the report

Constraints

Do NOT generate spec.json — this is a lighter tool than /specify
Do NOT start implementing changes — only analyze
Do NOT interview the user beyond one clarifying question
Do NOT run agents sequentially when they can run in parallel
Maximum wall-clock time target: ~90 seconds (two parallel rounds)