claude-code-workflow 7.2.13 → 7.2.15

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

@@ -72,6 +72,12 @@ All `AskUserQuestion` calls MUST comply:
 
 **Principles**: Immediacy (record as-it-happens), Completeness (context+options+chosen+reason+rejected), Traceability (later phases trace back), Depth (capture reasoning, not just outcomes)
 
+**Technical Solution Triggers** — record using Technical Solution Record Format when ANY of:
+- An implementation approach is described with specific files/patterns/code changes
+- Two or more alternatives are compared with trade-offs
+- User confirms, modifies, or rejects a proposed approach
+- A concrete code change strategy emerges (what to modify, how, why)
+
 ### Output Artifacts
 
 | Phase | Artifact | Description |
@@ -325,36 +331,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} | Do NOT re-discover files — us
 - Present to user at beginning of Phase 3: "初始探索完成后，以下意图的覆盖情况：[list]。接下来的讨论将重点关注未覆盖的部分。"
 - Purpose: Early course correction — catch drift before spending multiple interactive rounds
 
-**exploration-codebase.json Schema** (shared Layer 1):
-- `session_id`, `timestamp`, `topic`, `dimensions[]`
-- `relevant_files[]`: {path, annotation, dimensions[]}
-- `patterns[]`, `module_map`: {}
-- `questions_for_user[]`, `_metadata`
-
-**research.json Schema** (external research findings):
-- `topic`, `mode` (detail-verification|api-research|design-research), `timestamp`
-- `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, results_found}
-
-**explorations.json Schema** (single — Layer 1 + CLI analysis + research merged):
-- `session_id`, `timestamp`, `topic`, `dimensions[]`
-- `sources[]`: {type, file/summary}
-- `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
-- `call_chains[]`: {entry, chain, files}
-- `discussion_points[]`, `open_questions[]`
-- `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
-- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
-
-**perspectives.json Schema** (multi — Layer 1 shared + per-perspective Layer 2-3 + research):
-- `shared_discovery`: {relevant_files[], patterns[], module_map}
-- `perspectives[]`: [{name, tool, findings, insights, questions, code_anchors[], call_chains[]}]
-- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
-- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
+> All JSON schemas consolidated in `<schemas>` section below.
 
 | Condition | Action |
 |-----------|--------|
@@ -402,12 +379,23 @@ const priorContext = `
 
 4. **Process Response** (always record user choice + impact to discussion.md):
 
+   **Record-Before-Continue Rule**: Each path below MUST write findings and discussion synthesis to `discussion.md` BEFORE proceeding to Step 5. Specifically, after agent/CLI returns results:
+   - Append the exploration results, reasoning, and any technical approaches discussed to the current round section
+   - Apply **Technical Solution Triggers** (see Decision Recording Protocol) — if triggered, record using Technical Solution Record Format
+   - **Ambiguity Check**: For each Technical Solution with Status `Proposed`, verify no unresolved alternatives remain. If a solution lists 2+ options without a chosen one (e.g., "A or B"), record as:
+     ```markdown
+     > **⚠️ Ambiguity**: [Solution] has [N] unresolved alternatives: [list]
+     > - **Needs**: [Decision criteria or exploration to resolve]
+     ```
+     Surface unresolved ambiguities to user in the next feedback round.
+   - Only THEN proceed to Step 5 for Current Understanding replacement and TOC update
+
    **继续深入** -> Sub-question to choose direction (AskUserQuestion, single-select, header: "深入方向"):
    - Dynamically generate **max 3** context-driven options from: unresolved questions, low-confidence findings, unexplored dimensions, user-highlighted areas
    - Add **1** heuristic option that breaks current frame (e.g., "compare with best practices", "review from security perspective", "explore simpler alternatives")
    - Total: **max 4 options**. Each specifies: label, description, tool (cli-explore-agent for code-level / Gemini CLI for pattern-level), scope
    - **"Other" is auto-provided** by AskUserQuestion — covers user-specified custom direction (no need for separate "suggest next step" option)
-   - Execute selected direction -> merge new code_anchors/call_chains -> record confirmed assumptions + deepen angle
+   - Execute selected direction -> merge new code_anchors/call_chains into explorations.json -> **write exploration results, analysis reasoning, and any proposed approaches to discussion.md** -> record confirmed assumptions + deepen angle
 
    **外部研究** -> Spawn workflow-research-agent for targeted research:
    - AskUserQuestion (header: "研究主题", freetext via "Other"): What specific technology/pattern/approach needs external research?
@@ -420,9 +408,7 @@ const priorContext = `
 
    **分析完成** -> Exit loop -> Record why concluding
 
-5. **Update discussion.md**:
-   - **Append** Round N: user input, direction adjustment, Q&A, corrections, new insights
-   - **Append Technical Solutions** — for every solution proposed, validated, or rejected this round, record immediately using Technical Solution Record Format in `#### Technical Solutions`
+5. **Update discussion.md** (after Record-Before-Continue writes are done):
    - **Replace** `## Current Understanding` block with latest consolidated understanding (follow Consolidation Rules)
    - **Update** `## Table of Contents` with links to new Round N sections
 
@@ -477,6 +463,7 @@ const priorContext = `
    - Compile Decision Trail from all phases
    - Key conclusions with evidence + confidence (high/medium/low)
    - Recommendations with rationale + priority (high/medium/low) — **merge validated `technical_solutions[]` from explorations.json as high-priority recommendations**
+   - **Solution Readiness Gate**: For each recommendation, check if all key choices are resolved. Flag `ambiguity_resolved: false` on any recommendation that still contains unresolved alternatives. Present unresolved items to user before proceeding to Step 3.
    - Open questions, follow-up suggestions
    - Decision summary linking conclusions back to decisions
    - Write to conclusions.json
@@ -621,7 +608,45 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 
    **TodoWrite**: Update `next-step` -> `"completed"` after user selection is handled
 
-**conclusions.json Schema**:
+> conclusions.json schema: see `<schemas>` section below.
+</step>
+
+</process>
+
+<schemas>
+
+**exploration-codebase.json** (shared Layer 1):
+- `session_id`, `timestamp`, `topic`, `dimensions[]`
+- `relevant_files[]`: {path, annotation, dimensions[]}
+- `patterns[]`, `module_map`: {}
+- `questions_for_user[]`, `_metadata`
+
+**research.json** (external research findings):
+- `topic`, `mode` (detail-verification|api-research|design-research), `timestamp`
+- `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, results_found}
+
+**explorations.json** (single — Layer 1 + CLI analysis + research merged):
+- `session_id`, `timestamp`, `topic`, `dimensions[]`
+- `sources[]`: {type, file/summary}
+- `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
+- `call_chains[]`: {entry, chain, files}
+- `discussion_points[]`, `open_questions[]`
+- `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
+- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
+
+**perspectives.json** (multi — Layer 1 shared + per-perspective Layer 2-3 + research):
+- `shared_discovery`: {relevant_files[], patterns[], module_map}
+- `perspectives[]`: [{name, tool, findings, insights, questions, code_anchors[], call_chains[]}]
+- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
+- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
+
+**conclusions.json**:
 - `session_id`, `topic`, `completed`, `total_rounds`, `summary`
 - `key_conclusions[]`: {point, evidence, confidence, code_anchor_refs[]}
 - `code_anchors[]`: {file, lines, snippet, significance}
@@ -631,9 +656,8 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 - `decision_trail[]`: {round, decision, context, options_considered, chosen, rejected_reasons, reason, impact}
 - `narrative_trail[]`: {round, starting_point, key_progress, hypothesis_impact, updated_understanding, remaining_questions}
 - `intent_coverage[]`: {intent, status, where_addressed, notes}
-</step>
 
-</process>
+</schemas>
 
 <error_codes>
 
@@ -721,9 +745,6 @@ Present 2-3 top directions per dimension, allow multi-select + custom.
 | Preserve key learnings | Keep insights valuable for future reference |
 
 </configuration>
-
-> **Lite-plan handoff**: Phase 4「执行任务」builds structured `handoff-spec` JSON (implementation_scope with acceptance_criteria, code_anchors, key_findings) embedded in `## Prior Analysis` block. lite-plan parses `json:handoff-spec` to directly map scope items → tasks, skipping exploration and using acceptance_criteria as convergence.criteria.
-
 ---
 
 **Now execute analyze-with-file for**: $ARGUMENTS

package/.claude/skills/workflow-lite-plan/SKILL.md

@@ -340,9 +340,6 @@ Generate implementation plan and write plan.json.
 - ${sessionFolder}/plan.json (plan overview — NO embedded tasks[])
 - ${sessionFolder}/.task/TASK-*.json (independent task files, one per task)
 
-## Schema Reference
-Execute: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
-
 ## Project Context (MANDATORY)
 Execute: ccw spec load --category planning
 **CRITICAL**: All generated tasks MUST comply with constraints in specs/*.md
@@ -392,7 +389,6 @@ ${complexity}
 ## Requirements
 - _metadata.exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))}
 - Two-layer output: plan.json (task_ids[], NO tasks[]) + .task/TASK-*.json
-- Follow plan-overview-base-schema.json for plan.json, task-schema.json for .task/*.json
 - Field names: files[].change (not modification_points), convergence.criteria (not acceptance)
 
 ## Task Grouping Rules
@@ -405,9 +401,9 @@ ${complexity}
 7. **Prefer parallel**: Most tasks should be independent
 
 ## Execution
-1. Read schema → 2. ccw spec load → 3. Read ALL exploration files → 4. Synthesize + generate
-5. Write: planning-context.md, .task/TASK-*.json, plan.json (task_ids[], NO tasks[])
-6. Return brief completion summary
+1. ccw spec load → 2. Read ALL exploration files → 3. Synthesize + generate
+4. Write: planning-context.md, .task/TASK-*.json, plan.json (task_ids[], NO tasks[])
+5. Return brief completion summary
 `
 )
 ```