claude-code-workflow 7.2.11 → 7.2.12

package/.claude/commands/workflow/analyze-with-file.md

@@ -78,10 +78,10 @@ All `AskUserQuestion` calls MUST comply:
 |-------|----------|-------------|
 | 1 | `discussion.md` | Initialized with TOC, Current Understanding block, timeline, metadata |
 | 1 | Session variables | Dimensions, focus areas, analysis depth |
-| 2 | `exploration-codebase.json` | Single codebase context from cli-explore-agent |
-| 2 | `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) |
-| 2 | `explorations.json` | Single perspective aggregated findings |
-| 2 | `perspectives.json` | Multi-perspective findings (up to 4) with synthesis |
+| 2 | `exploration-codebase.json` | Shared Layer 1 discovery (files, modules, patterns) — always created |
+| 2 | `explorations/*.json` | Per-perspective Layer 2-3 deep-dives (multi-perspective only, max 4) |
+| 2 | `explorations.json` | Single perspective aggregated findings (Layer 1 + CLI analysis) |
+| 2 | `perspectives.json` | Multi-perspective findings (Layer 1 shared + per-perspective deep-dives) with synthesis |
 | 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced |
 | 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round |
 | 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) |
@@ -141,92 +141,124 @@ All `AskUserQuestion` calls MUST comply:
 <step name="cli_exploration">
 **Phase 2: Codebase exploration FIRST, then CLI analysis.**
 
-**Step 1: Codebase Exploration** (cli-explore-agent, parallel up to 6)
+**Step 1: Codebase Exploration** (cli-explore-agent, 1 shared + N perspective-specific)
 
-- **Single**: General codebase analysis -> `{sessionFolder}/exploration-codebase.json`
-- **Multi-perspective**: Parallel per-perspective -> `{sessionFolder}/explorations/{perspective}.json`
-- **Common tasks**: `ccw tool exec get_modules_by_depth '{}'`, keyword searches, read `.workflow/project-tech.json`
+Two-phase approach to avoid redundant file discovery:
+
+**Phase A — Shared Discovery** (1 agent, always runs):
+One cli-explore-agent performs Layer 1 (breadth) for ALL perspectives -> `{sessionFolder}/exploration-codebase.json`
 
 ```javascript
-// Template for cli-explore-agent (single or per-perspective)
+// Shared Layer 1 discovery — runs ONCE regardless of perspective count
 Agent({
   subagent_type: "cli-explore-agent",
   run_in_background: false,
-  description: `Explore codebase: ${topicSlug}`,
+  description: `Discover codebase: ${topicSlug}`,
   prompt: `
 ## Analysis Context
 Topic: ${topic_or_question}
 Dimensions: ${dimensions.join(', ')}
-// For multi-perspective, add: Perspective: ${perspective.name} - ${perspective.focus}
 Session: ${sessionFolder}
 
 ## MANDATORY FIRST STEPS
 1. Run: ccw tool exec get_modules_by_depth '{}'
 2. Read: .workflow/project-tech.json (if exists)
 
-## Layered Exploration (MUST follow all 3 layers)
+## Layer 1 — Module Discovery (Breadth ONLY)
+- Search by topic keywords across ALL dimensions: ${dimensions.join(', ')}
+- Identify ALL relevant files, map module boundaries and entry points
+- Categorize files by dimension/perspective relevance
+- Output: relevant_files[] with annotations + dimension tags, initial patterns[]
+
+## Output
+Write to: ${sessionFolder}/exploration-codebase.json
+Schema: {relevant_files: [{path, annotation, dimensions[]}], patterns[], module_map: {}, questions_for_user, _metadata}
+`
+})
+```
+
+**Phase B — Perspective Deep-Dive** (parallel, only for multi-perspective, max 4):
+Each perspective agent receives shared Layer 1 results, performs only Layer 2-3 on its relevant subset.
+Skip if single-perspective (single mode proceeds directly to Step 2 CLI analysis with Layer 1 results).
+
+```javascript
+// Per-perspective Layer 2-3 — receives shared discovery, avoids re-scanning
+// Only runs in multi-perspective mode
+const sharedDiscovery = readJSON(`${sessionFolder}/exploration-codebase.json`)
+const perspectiveFiles = sharedDiscovery.relevant_files
+  .filter(f => f.dimensions.includes(perspective.dimension))
+
+selectedPerspectives.forEach(perspective => {
+  Agent({
+    subagent_type: "cli-explore-agent",
+    run_in_background: false,
+    description: `Deep-dive: ${perspective.name}`,
+    prompt: `
+## Analysis Context
+Topic: ${topic_or_question}
+Perspective: ${perspective.name} - ${perspective.focus}
+Session: ${sessionFolder}
 
-### Layer 1 — Module Discovery (Breadth)
-- Search by topic keywords, identify ALL relevant files
-- Map module boundaries and entry points -> relevant_files[] with annotations
+## SHARED DISCOVERY (Layer 1 already completed — DO NOT re-scan)
+Relevant files for this perspective:
+${perspectiveFiles.map(f => `- ${f.path}: ${f.annotation}`).join('\n')}
+Patterns found: ${sharedDiscovery.patterns.join(', ')}
 
-### Layer 2 — Structure Tracing (Depth)
-- Top 3-5 key files: trace call chains 2-3 levels deep
+## Layer 2 — Structure Tracing (Depth)
+- From the relevant files above, pick top 3-5 key files for this perspective
+- Trace call chains 2-3 levels deep
 - Identify data flow paths and dependencies -> call_chains[], data_flows[]
 
-### Layer 3 — Code Anchor Extraction (Detail)
+## Layer 3 — Code Anchor Extraction (Detail)
 - Each key finding: extract code snippet (20-50 lines) with file:line
-- Annotate WHY this matters -> code_anchors[]
+- Annotate WHY this matters for ${perspective.name} -> code_anchors[]
 
 ## Output
-Write to: ${sessionFolder}/exploration-codebase.json
-// Multi-perspective: ${sessionFolder}/explorations/${perspective.name}.json
-
-Schema: {relevant_files, patterns, key_findings, code_anchors: [{file, lines, snippet, significance}], call_chains: [{entry, chain, files}], questions_for_user, _metadata}
+Write to: ${sessionFolder}/explorations/${perspective.name}.json
+Schema: {perspective, relevant_files, key_findings, code_anchors: [{file, lines, snippet, significance}], call_chains: [{entry, chain, files}], questions_for_user, _metadata}
 `
+  })
 })
 ```
 
-**Step 2: CLI Analysis** (AFTER exploration)
+**Step 2: CLI Deep Analysis** (AFTER exploration, single-perspective ONLY)
 
-- **Single**: Comprehensive CLI analysis with exploration context
-- **Multi (up to 4)**: Parallel CLI calls per perspective
+- **Single-perspective**: CLI does Layer 2-3 depth analysis (explore agent only did Layer 1)
+- **Multi-perspective**: SKIP this step — perspective agents in Step 1 Phase B already did Layer 2-3
 - Execution: `Bash` with `run_in_background: true`
 
 ```javascript
-// Build shared exploration context for CLI prompts
-const explorationContext = `
-PRIOR EXPLORATION CONTEXT:
-- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
-- Patterns: ${explorationResults.patterns.slice(0,3).join(', ')}
-- Findings: ${explorationResults.key_findings.slice(0,3).join(', ')}
-- Code anchors:
-${(explorationResults.code_anchors || []).slice(0,5).map(a => `  [${a.file}:${a.lines}] ${a.significance}\n  \`\`\`\n  ${a.snippet}\n  \`\`\``).join('\n')}
-- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} -> ${c.chain.join(' -> ')}`).join('; ')}`
-
-// Single perspective (for multi: loop selectedPerspectives with perspective.purpose/tasks/constraints)
-Bash({
-  command: `ccw cli -p "
-PURPOSE: Analyze '${topic_or_question}' from ${dimensions.join(', ')} perspectives
-Success: Actionable insights with clear reasoning
+// ONLY for single-perspective mode — multi-perspective already has deep-dive agents
+if (selectedPerspectives.length <= 1) {
+  const sharedDiscovery = readJSON(`${sessionFolder}/exploration-codebase.json`)
+  const explorationContext = `
+PRIOR EXPLORATION (Layer 1 discovery):
+- Key files: ${sharedDiscovery.relevant_files.slice(0,8).map(f => `${f.path} (${f.annotation})`).join(', ')}
+- Patterns: ${sharedDiscovery.patterns.slice(0,5).join(', ')}
+- Module map: ${JSON.stringify(sharedDiscovery.module_map || {})}`
+
+  Bash({
+    command: `ccw cli -p "
+PURPOSE: Deep analysis of '${topic_or_question}' — build on prior file discovery
+Success: Actionable insights with code evidence (anchors + call chains)
 
 ${explorationContext}
 
 TASK:
-- Build on exploration findings — reference specific code anchors
-- Analyze common patterns and anti-patterns with code evidence
-- Highlight potential issues/opportunities with file:line references
+- From discovered files, trace call chains 2-3 levels deep for top 3-5 key files
+- Extract code snippets (20-50 lines) for each key finding with file:line
+- Identify patterns, anti-patterns, and potential issues with evidence
 - Generate discussion points for user clarification
 
 MODE: analysis
 CONTEXT: @**/* | Topic: ${topic_or_question}
-EXPECTED: Structured analysis with sections, insights tied to evidence, questions, recommendations
-CONSTRAINTS: Focus on ${dimensions.join(', ')}
+EXPECTED: Structured analysis with: key_findings[], code_anchors[{file,lines,snippet,significance}], call_chains[{entry,chain,files}], discussion_points[]
+CONSTRAINTS: Focus on ${dimensions.join(', ')} | Do NOT re-discover files — use provided file list
 " --tool gemini --mode analysis`,
-  run_in_background: true
-})
-// STOP: Wait for hook callback before continuing
-// Multi-perspective: Same pattern per perspective with perspective.purpose/tasks/constraints/tool
+    run_in_background: true
+  })
+  // STOP: Wait for hook callback before continuing
+}
 ```
 
 **Step 3: Aggregate Findings**
@@ -243,7 +275,13 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 - Present to user at beginning of Phase 3: "初始探索完成后，以下意图的覆盖情况：[list]。接下来的讨论将重点关注未覆盖的部分。"
 - Purpose: Early course correction — catch drift before spending multiple interactive rounds
 
-**explorations.json Schema** (single):
+**exploration-codebase.json Schema** (shared Layer 1):
+- `session_id`, `timestamp`, `topic`, `dimensions[]`
+- `relevant_files[]`: {path, annotation, dimensions[]}
+- `patterns[]`, `module_map`: {}
+- `questions_for_user[]`, `_metadata`
+
+**explorations.json Schema** (single — Layer 1 + CLI analysis merged):
 - `session_id`, `timestamp`, `topic`, `dimensions[]`
 - `sources[]`: {type, file/summary}
 - `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
@@ -251,10 +289,10 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 - `discussion_points[]`, `open_questions[]`
 - `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
 
-**perspectives.json Schema** (multi — extends explorations.json):
-- `perspectives[]`: [{name, tool, findings, insights, questions}]
+**perspectives.json Schema** (multi — Layer 1 shared + per-perspective Layer 2-3):
+- `shared_discovery`: {relevant_files[], patterns[], module_map}
+- `perspectives[]`: [{name, tool, findings, insights, questions, code_anchors[], call_chains[]}]
 - `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
-- code_anchors/call_chains include `perspective` field
 
 | Condition | Action |
 |-----------|--------|
@@ -270,6 +308,22 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 
 **Guideline**: Delegate complex tasks to agents (cli-explore-agent) or CLI calls. Avoid direct analysis in main process.
 
+**Cumulative Context Rule**: Every agent/CLI call in Phase 3 MUST include a summary of ALL prior exploration results to avoid re-discovering known information. Build `priorContext` before each call:
+```javascript
+// Build cumulative context from all prior explorations (Phase 2 + previous rounds)
+const allFindings = readJSON(`${sessionFolder}/explorations.json`) // or perspectives.json
+const priorContext = `
+## KNOWN FINDINGS (DO NOT re-discover)
+- Established files: ${allFindings.sources.map(s => s.file).join(', ')}
+- Key findings: ${allFindings.key_findings.join('; ')}
+- Code anchors: ${allFindings.code_anchors.slice(0,5).map(a => `${a.file}:${a.lines}`).join(', ')}
+- Call chains: ${allFindings.call_chains.slice(0,3).map(c => c.entry).join(', ')}
+- Open questions: ${allFindings.open_questions.join('; ')}
+
+## NEW TASK: Focus ONLY on unexplored areas below.
+`
+```
+
 **Loop** (max 5 rounds):
 
 1. **Current Understanding Summary** (Round >= 2, BEFORE presenting new findings):