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

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 "执行任务")

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:

{
  "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. 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, 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):

• 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:

• 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]):

Overall confidence = weighted average across dimensions. Identify weakest dimension.

Update state.json confidence section. Append confidence table to discussion.md:

#### Confidence Score (Baseline)
| Dimension | Depth | Evidence | Coverage | Validation | Consistency | **Score** |
|-----------|-------|----------|----------|------------|-------------|-----------|
| {dim}     | {x}   | {x}     | {x}      | 0.00       | {x}         | **{x}**   |

Overall: {N}% | Weakest: {dim} ({N}%)
> < 60%: 建议继续深入 | 60-80%: 可选深入或收敛 | > 80%: 建议收敛到结论

Phase 2 exit criteria: exploration-codebase.json created (if codebase), research.json created (if topic warrants), discussion.md updated with Round 1, initial intent coverage check done, baseline confidence computed.

Mark phase-2 completed, phase-3 in_progress.

Phase 3: Interactive Discussion

Max 5 rounds. Each round follows this sequence.

Cumulative Context Rule

Every analysis action in Phase 3 MUST include a summary of ALL prior findings to avoid re-discovering known information:

## KNOWN FINDINGS (DO NOT re-discover)
- Established files: {list from exploration-codebase.json}
- Key findings: {from discussion.md rounds}
- Open questions: {remaining}
## NEW TASK: Focus ONLY on unexplored areas below.

3.1 Present Findings & Gather Direction

Round ≥ 2 preamble: 1-2 sentence recap of established consensus + last round's direction + confidence delta. Example: "到目前为止，我们已确认 [facts]。上一轮 [direction]。Confidence 从 52% 提升到 67%，security 维度仍需深入。"

Read latest confidence from state.json. Identify weakest dimension.

Present via functions.request_user_input (single question, multiSelect: false, 4 options):

• 继续深入: {weakest_dimension} (Recommended) — deepen the lowest-confidence dimension
• 外部研究 — web.run for specific technology/pattern
• 调整方向 — different focus or specific questions
• 分析完成 — proceed to synthesis (triggers readiness gate)

Question header shows: Round {N} | Confidence: {N}% | 最弱: {dim} ({N}%)

3.2 Process Response

Record-Before-Continue Rule: Each path below MUST write findings and discussion synthesis to discussion.md BEFORE proceeding to state update or next round.

Recording Checkpoint (all paths): Record user's original choice, impact on direction, and full Decision Record if direction changed.

Technical Solution Triggers: When an implementation approach is described with specific files/patterns, 2+ alternatives compared, or user confirms/rejects an approach → record using Technical Solution format.

Ambiguity Check: For each Technical Solution with Status "Proposed", verify no unresolved alternatives remain. If 2+ options without a chosen one → flag:

> **⚠️ Ambiguity**: [Solution] has [N] unresolved alternatives: [list]
> - **Needs**: [Decision criteria or exploration to resolve]

Surface to user in next feedback round.

继续深入

Ask sub-question via functions.request_user_input (multiSelect: false, max 4 total):

• Up to 3 context-driven options generated from: unresolved questions, low-confidence findings, unexplored dimensions
• 1 heuristic option: "换角度审视" — compare with best practices / different perspective / simpler alternatives
• "Other" auto-provided for user-specified custom direction

Execute inline search using Grep/Glob/Read/mcp__ace-tool__search_context. Merge new findings with prior context. Record confirmed assumptions and exploration angles.

外部研究

Ask research topic via functions.request_user_input (max 4 options):

• Up to 3 suggestions from: unresolved tech questions, unvalidated patterns
• 1 custom option: "自定义" (via Other)

Execute web.run({search_query: "{topic} best practices {year}"}). Merge findings into research.json (append, don't overwrite). Record as Key Findings in discussion.md. Cross-reference with codebase; flag new codebase_gaps.

调整方向

Ask new focus. Analyze from adjusted perspective. Compare new insights with prior analysis. Record as Decision: trigger, old→new direction, expected impact.

分析完成

Trigger Pre-Synthesis Readiness Gate. If passed → exit to Phase 4. If blocked → user chooses to address gaps or accept risk (residual risks recorded in state.json + discussion.md).

Record why concluding at this round.

3.3 Document Round

Append to Discussion Timeline using Round Template: User Input, Decision Log, Key Findings, Technical Solutions, Analysis Results, Corrected Assumptions, Open Items, Confidence Score, Narrative Synthesis.

Overwrite (not append) ## Current Understanding with latest consolidated state following Consolidation Rules.

Update ## Table of Contents with new Round N links.

3.4 Quality Mechanisms

Execute after documenting each round.

Pressure Pass (mandatory, at least once before Phase 4)

When quality.pressure_pass_done is false and current round has key findings:

Select the highest-confidence finding and apply the pressure ladder in sequence:

1. Evidence demand: "What concrete evidence supports this? Is there a counter-example?"
2. Assumption probe: "What hidden assumption makes this true? What dependency does this rest on?"
3. Boundary/tradeoff: "If we accept this, what must we give up or explicitly exclude?"
4. Root cause check: "Is this the root cause, or a symptom of something deeper?"

Stay on the same finding until validated or corrected — don't rotate for coverage. A finding that survives is promoted to high-confidence; one that doesn't is flagged.

Record in discussion.md:

#### Pressure Pass (Round N)
> **Target**: [finding]
> - **Confidence claimed**: [level] | **Evidence**: [assessment]
> - **Hidden assumption**: [identified]
> - **Boundary impact**: [tradeoff or scope consequence]
> - **Verdict**: [Confirmed with evidence / Weakened — needs more data / Corrected]

Set quality.pressure_pass_done = true in state.json.

Challenge Mode Injection (automatic, round ≥ 2)

Each mode fires at most once per session. Track in quality.challenge_modes_used[].

Record in discussion.md:

#### Challenge: {Mode}
> **Target**: [finding or observation]
> **Counter-scenario / Question**: [challenge content]
> **Result**: [survived / weakened / corrected]

Stall Detection

After each round, assess: new findings? corrected assumptions? confidence delta > 5%?

If NONE of these for 2 consecutive rounds (quality.stall_counter >= 2):

• Auto-inject Root Cause Probe (if unused)
• Surface to user via functions.request_user_input (3 options):
  • 换维度 (Recommended): switch to weakest or unexplored dimension
  • 外部研究: break deadlock with external best practices
  • 收敛结论: current findings sufficient, proceed to synthesis
• Reset stall counter

Re-score Confidence

Re-compute all dimension scores. user_validation factor increases as user confirms findings across rounds.

Update state.json: confidence.dimensions, confidence.overall, confidence.weakest, append to confidence.history[{round, overall, dimensions}].

Append to discussion.md:

#### Confidence Score (Round N)
Overall: {N}% ({+/-N}%) | Weakest: {dim} ({N}%)

3.5 Pre-Synthesis Readiness Gate

Triggered when user selects "分析完成". Block exit if ANY:

1. ❌ intents exist in latest coverage check
2. Any dimension below 40% confidence without explicit deferral
3. quality.pressure_pass_done is false
4. Unresolved Technical Solution ambiguities (Proposed status with 2+ alternatives)

If gaps found → present via functions.request_user_input (2 options):

• 补充后完成 (Recommended): Continue Phase 3 targeting gaps
• 忽略风险并继续: Record residual risks in state.json quality.residual_risks[] + discussion.md, proceed to Phase 4