analyze-with-file

# Analyze-With-File Interactive collaborative analysis with documented discussion process. Records understanding evolution, facilitates multi-round Q&A, and uses inline search + external research for deep exploration. **Core flow**: Topic → Explore → Discuss → Refine → Conclude → Next Step **Auto mode** (`-y`): Auto-confirm exploration decisions, use recommended angles, skip interactive scoping. ## Configuration | Flag | Default | Description | |------|---------|-------------| | `-y, --yes` | false | Auto-confirm all decisions | | `--continue` | false | Continue existing session | | `--depth` | standard | quick / standard / deep | **Session ID**: `ANL-{YYYY-MM-DD}-{slug}` - slug: `topic.toLowerCase()` → keep `[a-z0-9\u4e00-\u9fa5]`, replace rest with `-`, max 40 chars - date: YYYY-MM-DD in UTC+8 - Auto-detect continue: session folder + discussion.md exists → continue mode ## Artifacts ``` {projectRoot}/.workflow/.analysis/ANL-{date}-{slug}/ ├── discussion.md # Single source of truth: rounds, decisions, conclusions, synthesis ├── state.json # Session state: config, confidence, quality tracking ├── exploration-codebase.json # Codebase exploration: files, patterns, constraints ├── research.json # External research: best practices, pitfalls, sources └── handoff.json # Structured handoff (only on "执行任务") ``` | File | When Created | Purpose | |------|-------------|---------| | `discussion.md` | Phase 1 | All analysis content: session metadata, round-by-round findings, multi-perspective synthesis, decisions, intent coverage, conclusions, recommendations. **Overwritten** sections: `## Current Understanding`. **Appended** sections: `## Discussion Timeline`. | | `state.json` | Phase 0 | Machine-readable: current round, dimension scores, confidence history, quality tracking (pressure pass, challenge modes, stall counter), exploration metadata. Updated every round. | | `exploration-codebase.json` | Phase 2 | Codebase context: `project_type`, `relevant_files[{path, relevance, summary, dimensions[]}]`, `patterns[{pattern, files, description}]`, `constraints[]`, `integration_points[{location, description}]`, `key_findings[]`, `_metadata{timestamp, exploration_scope}` | | `research.json` | Phase 2 | External research: `findings[{finding, detail, confidence, source_url}]`, `best_practices[{practice, rationale, source}]`, `alternatives[{option, pros, cons, verdict}]`, `pitfalls[{issue, mitigation, source}]`, `codebase_gaps[{gap, current_approach, recommended_approach}]`, `sources[{title, url, key_takeaway}]` | | `handoff.json` | Phase 4 | Only on "执行任务": `source`, `session_id`, `session_folder`, `summary`, `implementation_scope[{objective, rationale, priority, target_files[], acceptance_criteria[], change_summary}]`, `code_anchors[]`, `key_files[]`, `key_findings[]`, `decision_context[]`, `exploration_artifacts{exploration_codebase, research}` — keys align with workflow-lite-plan artifactMapping | --- ## Analysis Flow ``` Phase 0: Session Setup ├─ Parse topic, flags, generate session ID ├─ Detect project root (git rev-parse --show-toplevel || pwd) ├─ Create session folder (or detect existing → continue) ├─ Initialize state.json + discussion.md └─ functions.update_plan([phase-1..phase-4, next-step]) Phase 1: Topic Understanding ├─ Identify analysis dimensions from topic keywords ├─ Scope with user: focus, perspectives (1-4), depth ├─ Generate initial questions from dimensions └─ Write initial sections to discussion.md Phase 2: Exploration ├─ Load project specs (ccw spec load) ├─ Codebase search → exploration-codebase.json ├─ External research via web.run → research.json ├─ Multi-perspective analysis → write to discussion.md ├─ Context budget gate (>30 files → rank + trim) ├─ Initial intent coverage check └─ Baseline confidence scoring → state.json Phase 3: Interactive Discussion (max 5 rounds) ├─ Present findings + confidence + weakest dimension ├─ User direction: Deepen / Research / Adjust / Complete ├─ Cumulative context: always include prior findings ├─ Record-before-continue: write to discussion.md BEFORE state update ├─ Quality mechanisms: │ ├─ Pressure pass (mandatory ≥1 before Phase 4) │ ├─ Challenge injection (auto, round ≥2) │ ├─ Stall detection (2 consecutive no-progress rounds) │ └─ Re-score confidence → state.json ├─ Pre-synthesis readiness gate (on "Complete") ├─ Intent drift check (round ≥2) └─ Update discussion.md: append round + overwrite Current Understanding Phase 4: Synthesis & Terminal Gate ├─ Intent Coverage Verification (mandatory gate) ├─ Findings → Recommendations Traceability (mandatory gate) ├─ Write synthesis + conclusions to discussion.md ├─ Recommendation review with user └─ Terminal gate: 执行任务 → handoff.json | 产出Issue | 完成 ``` --- ## Phase 0: Session Setup 1. Parse `{{ARGUMENTS}}` for topic, flags (`--depth`, `--continue`, `-y`) 2. Detect project root: `git rev-parse --show-toplevel 2>/dev/null || pwd` 3. Generate session ID: `ANL-{date}-{slug}`, session folder: `{projectRoot}/.workflow/.analysis/{sessionId}` 4. If session folder + discussion.md exists → auto-enter continue mode (load state.json, resume from last round) 5. Create session folder: `mkdir -p {sessionFolder}` 6. Initialize `state.json`: ```json { "session_id": "ANL-{date}-{slug}", "topic": "...", "depth": "standard", "dimensions": [], "perspectives": [], "focus_areas": [], "current_round": 0, "current_phase": "setup", "confidence": { "dimensions": {}, "overall": 0, "weakest": null, "history": [] }, "quality": { "pressure_pass_done": false, "challenge_modes_used": [], "stall_counter": 0, "last_findings_count": 0, "readiness_gate_passed": false, "residual_risks": [] } } ``` 7. Initialize progress tracking: ``` functions.update_plan([ { id: "phase-1", title: "Phase 1: Topic Understanding", status: "in_progress" }, { id: "phase-2", title: "Phase 2: Exploration & Research", status: "pending" }, { id: "phase-3", title: "Phase 3: Interactive Discussion", status: "pending" }, { id: "phase-4", title: "Phase 4: Synthesis & Conclusion", status: "pending" }, { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" } ]) ``` --- ## Phase 1: Topic Understanding ### 1.1 Identify Dimensions Match topic keywords against [Analysis Dimensions](#analysis-dimensions). If multiple match, include all. If none match, default to "architecture" + "implementation". ### 1.2 Initial Scoping (new session, not auto mode) Single `functions.request_user_input` call with up to 3 questions (constraint: 1-4 questions, 2-4 options each): **Question 1 — Focus areas** (multiSelect: true): - Generate options dynamically from matched dimensions using [Dimension-Direction Mapping](#dimension-direction-mapping), max 4 options **Question 2 — Perspectives** (multiSelect: true): - Technical: Implementation patterns, code structure, feasibility - Architectural: System design, scalability, interactions - Security: Security patterns, vulnerabilities, access control - Performance: Bottlenecks, optimization, resource utilization Max 4 perspectives. Single perspective is default. **Question 3 — Depth** (multiSelect: false): - Standard (Recommended): Balanced analysis with good coverage - Quick Overview: Fast surface-level understanding - Deep Dive: Comprehensive multi-round investigation ### 1.3 Initialize discussion.md Write the full initial template (see [discussion.md Structure](#discussionmd-structure)): - Header: session ID, topic, timestamp (UTC+8), dimensions, depth - Table of Contents (auto-updated each round) - Current Understanding: "To be populated after exploration" - Analysis Context: focus areas, perspectives, depth - Initial Questions: generated from topic + dimensions (key questions that the analysis should answer) - Initial Decisions: record WHY these dimensions/focus areas were selected, what was excluded and why - Discussion Timeline: empty, rounds appended later - Decision Trail: empty, populated in Phase 4 Update state.json with dimensions, perspectives, focus_areas, depth. Mark phase-1 completed, phase-2 in_progress. --- ## Phase 2: Exploration All exploration done inline — no agent delegation. ### 2.1 Codebase Detection & Spec Loading Detect project type: - `package.json` → nodejs | `go.mod` → golang | `Cargo.toml` → rust | `pyproject.toml` → python | `pom.xml` → java | `src/` exists → generic | else → none If codebase detected, load project metadata: - `functions.exec_command('ccw spec load --category exploration')` - `functions.exec_command('ccw spec load --category debug')` - Read `.workflow/specs/*.md` for project conventions ### 2.2 Codebase Search Search using: **Grep**, **Glob**, **Read**, **mcp__ace-tool__search_context** Focus on: modules/components relevant to topic, code patterns/structure, integration points, config/dependencies. Write findings to `exploration-codebase.json` with full schema: - `project_type`: detected type - `relevant_files[]`: `{path, relevance, summary, dimensions[]}` - `patterns[]`: `{pattern, files, description}` - `constraints[]`: architectural constraints found - `integration_points[]`: `{location, description}` - `key_findings[]`: main insights from code search - `_metadata`: `{timestamp, exploration_scope}` ### 2.3 External Research **Trigger condition**: dimensions include `architecture|comparison|decision|performance|security`, OR topic matches `best practice|pattern|vs|compare|approach|standard|library|framework`. Skip for purely internal codebase questions (e.g., "how does module X work"). Execute up to 3 `web.run` queries: - `{topic} best practices {year}` - `{topic} common pitfalls and known issues` - Per matching dimension: `{topic} {dimension} patterns and recommendations` Write findings to `research.json` with full schema: - `findings[]`: `{finding, detail, confidence, source_url}` - `best_practices[]`: `{practice, rationale, source}` - `alternatives[]`: `{option, pros, cons, verdict}` - `pitfalls[]`: `{issue, mitigation, source}` - `codebase_gaps[]`: `{gap, current_approach, recommended_approach}` - `sources[]`: `{title, url, key_takeaway}` - `_metadata`: `{queries_executed, timestamp}` Cross-reference: flag where codebase patterns diverge from research best practices as `codebase_gaps`. ### 2.4 Multi-Perspective Analysis **Single perspective** (default): Comprehensive analysis across all dimensions using exploration + research context. Write findings directly to discussion.md Round 1. **Multi-perspective** (2-4 perspectives, serial): Analyze each perspective sequentially. For each perspective, write a summary subsection in discussion.md Round 1. Then append a synthesis subsection: - **Convergent themes**: what all perspectives agree on - **Conflicting views**: where perspectives differ - **Unique contributions**: insights unique to specific perspectives ### 2.5 Context Budget Gate If exploration found > 30 relevant files in `exploration-codebase.json`: - Rank by relevance score, keep top 30 per dimension - Update `exploration-codebase.json` with trimmed list + `_budget{original_count, summarized_count}` - Note in discussion.md: "探索发现 N 个相关文件，已精简至 30 个高相关文件" ### 2.6 Write Round 1 to discussion.md Append to Discussion Timeline using [Round Template](#round-template): - Sources analyzed, key findings with evidence refs (file:line) - External research findings, best practices, codebase gaps - Multi-perspective synthesis (if applicable) - Discussion points and open questions - Decision Log: why certain search strategies/perspectives were chosen ### 2.7 Initial Intent Coverage Check Extract original user intents from discussion.md header. Check each against Round 1 findings: - ✅ covered - 🔄 in-progress - ❌ not yet discussed Append to discussion.md: "接下来的讨论将重点关注未覆盖 (❌) 和进行中 (🔄) 的意图。" ### 2.8 Baseline Confidence Scoring Score each dimension on 5 weighted factors (each [0.0, 1.0]): | Factor | Weight | Measures | |--------|--------|----------| | findings_depth | 0.30 | How deep the findings go | | evidence_strength | 0.25 | Hard evidence vs inference | | coverage_breadth | 0.20 | How much of the dimension is covered | | user_validation | 0.15 | User confirmed findings (starts at 0, increases in Phase 3) | | consistency | 0.10 | Findings don't contradict | Overall confidence = weighted average across dimensions. Identify weakest dimension. Update state.json `confidence` section. Append confidence table to discussion.md: ```markdown #### Confidence Score (Baseline) | Dimension | Depth | Evidence | Coverage | Validation | Consistency | **Score** |