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

Content truncated.