refactor: simplify brainstorm synthesis phase - single agent + conditional review

- Remove Phase 5 (parallel role document update agents) - role analyses are now immutable - Merge Phase 6/6.5 into single Spec Agent that sequentially generates all feature specs, feature-index.json, and synthesis-changelog.md - Add conditional Review Agent triggered by complexity score (>= 4/8) - Reduce agent calls from (N_roles + N_features) to 1 Spec + 0~1 Review - Reduce total context from ~50K+ to ~15-20K words - Add 4 design principles: immutable role outputs, spec as final artifact, single agent sequential generation, on-demand review
2026-02-28 09:23:08 +08:00 · 2026-02-17 10:37:41 +08:00
parent 8ac4356d63
commit b23e822a35
2 changed files with 280 additions and 245 deletions
--- a/.claude/skills/brainstorm/SKILL.md
+++ b/.claude/skills/brainstorm/SKILL.md
@@ -35,8 +35,8 @@ Artifacts  N×Role  Synthesis  1×Role
 ```
 Auto Mode:
  Phase 2 (artifacts) → guidance-specification.md + selected_roles[]
-    → Phase 3 (N × role-analysis) → {role}/analysis*.md
-      → Phase 4 (synthesis) → feature-specs/ + feature-index.json
+    → Phase 3 (N × role-analysis) → {role}/analysis*.md (immutable)
+      → Phase 4 (synthesis) → feature-specs/ + feature-index.json + synthesis-changelog.md

 Single Role Mode:
  Phase 3 (1 × role-analysis) → {role}/analysis*.md
@@ -100,10 +100,10 @@ For ui-designer: append `--style-skill {package}` if provided.
 #### Phase 4: Synthesis Integration
   Ref: phases/04-synthesis.md

-Eight-phase cross-role synthesis: Discovery → File discovery → Cross-role analysis → User interaction → Document updates → Feature spec generation → Feature index → Finalization.
+Six-phase synthesis: Discovery → File discovery → Cross-role analysis → User interaction → Spec generation (single agent, sequential) + Conditional review → Finalization. Role analysis files are read-only (never modified). Spec is the final synthesis artifact.

-**Input**: session_id from Phase 2, all role analysis files from Phase 3
-**Output**: Updated analyses, feature-specs/, feature-index.json
+**Input**: session_id from Phase 2, all role analysis files from Phase 3 (read-only)
+**Output**: feature-specs/, feature-index.json, synthesis-changelog.md

 **TodoWrite**: Attach synthesis sub-tasks, execute sequentially, collapse on completion.

@@ -222,13 +222,13 @@ Phase 3:
  Input:  selected_roles[], session_id
          guidance-specification.md
          style_skill (for ui-designer)
-  Output: {role}/analysis*.md (N files)
+  Output: {role}/analysis*.md (N files, immutable after this point)
          ↓
 Phase 4:
-  Input:  session_id, all analysis files
-  Output: Updated analyses
-          feature-specs/F-{id}-{slug}.md
+  Input:  session_id, all analysis files (read-only)
+  Output: feature-specs/F-{id}-{slug}.md
          feature-index.json
+          synthesis-changelog.md
 ```

 ## TodoWrite Pattern
@@ -322,16 +322,17 @@ Initial → Phase 1 Mode Routing (completed)
 │   └── context-package.json           # Phase 0 output (auto mode)
 └── .brainstorming/
    ├── guidance-specification.md      # Framework (Phase 2, auto mode)
-    ├── feature-index.json             # Feature index (Phase 4, auto mode)
-    ├── feature-specs/                 # Feature specs (Phase 4, auto mode)
+    ├── feature-index.json             # Feature index (Phase 4, auto mode, feature_mode)
+    ├── synthesis-changelog.md         # Synthesis decisions audit trail (Phase 4, auto mode)
+    ├── feature-specs/                 # Feature specs (Phase 4, auto mode, feature_mode)
    │   ├── F-001-{slug}.md
    │   └── F-00N-{slug}.md
-    ├── {role}/
+    ├── {role}/                        # Role analyses (IMMUTABLE after Phase 3)
    │   ├── {role}-context.md          # Interactive Q&A responses
    │   ├── analysis.md                # Main/index document
    │   ├── analysis-cross-cutting.md  # Cross-feature (feature_mode)
    │   └── analysis-F-{id}-{slug}.md  # Per-feature (feature_mode)
-    └── synthesis-specification.md     # Integration (Phase 4, auto mode)
+    └── synthesis-specification.md     # Integration (Phase 4, non-feature_mode only)
 ```

 ## Error Handling
--- a/.claude/skills/brainstorm/phases/04-synthesis.md
+++ b/.claude/skills/brainstorm/phases/04-synthesis.md
@@ -1,17 +1,23 @@
 # Phase 4: Synthesis Integration

-Eight-phase workflow to eliminate ambiguities, enhance conceptual depth, and generate per-feature specifications through cross-role analysis and user clarification.
+Six-phase workflow to eliminate ambiguities, generate per-feature specifications through cross-role analysis and user clarification, with conditional quality review.

 ## Objective

- Discover and validate all role analysis files
+- Discover and validate all role analysis files (read-only, never modify originals)
 - Execute cross-role analysis to identify consensus, conflicts, and gaps
 - Present enhancement recommendations and clarification questions to user
- Update role analyses in parallel with enhancements and clarifications
- Generate consolidated feature specifications (feature_mode)
- Generate feature index for downstream consumers (feature_mode)
+- Generate consolidated feature specifications as final synthesis artifact
+- Conditional quality review based on task complexity
 - Update context package and session metadata

+## Design Principles
+
+1. **原始角色产出不可变** — 角色分析文档是各角色的原始视角，综合阶段只读不写
+2. **Spec 作为最终信物** — 所有综合决策、冲突解决、用户澄清都体现在 spec 中，不倒灌回角色文档
+3. **单 Agent 顺序生成** — 一个 Spec Agent 加载一次上下文，顺序生成所有 spec，跨 feature 决策可传递复用
+4. **按需校验** — Review Agent 由 Spec Agent 根据复杂度自判断触发，非必须环节
+
 ## Auto Mode

 When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions, use default answers.
@@ -25,11 +31,9 @@ When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions
 | 1 | Session detection | Main flow | session_id, brainstorm_dir |
 | 2 | File discovery | Main flow | role_analysis_paths |
 | 3A | Cross-role analysis | Agent | enhancement_recommendations, feature_conflict_map |
-| 4 | User interaction | Main flow + AskUserQuestion | update_plan |
-| 5 | Document updates | Parallel agents | Updated analysis*.md |
-| 6 | Feature spec generation | Parallel agents | feature-specs/F-{id}-{slug}.md [feature_mode] |
-| 6.5 | Feature index generation | Main flow | feature-index.json [feature_mode] |
-| 7 | Finalization | Main flow | context-package.json, report |
+| 4 | User interaction | Main flow + AskUserQuestion | spec_context |
+| 5 | Spec generation + conditional review | Spec Agent → Review Agent | feature-specs/, feature-index.json, synthesis-changelog.md |
+| 6 | Finalization | Main flow | context-package.json, report |

 ### AskUserQuestion Pattern

@@ -73,9 +77,8 @@ AskUserQuestion({
  {"content": "Execute analysis agent (cross-role analysis + feature conflict map)", "status": "pending", "activeForm": "Executing analysis"},
  {"content": "Present enhancements via AskUserQuestion", "status": "pending", "activeForm": "Selecting enhancements"},
  {"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"},
-  {"content": "Execute parallel update agents", "status": "pending", "activeForm": "Updating documents"},
-  {"content": "Generate parallel feature specs (feature_mode only)", "status": "pending", "activeForm": "Generating feature specs"},
-  {"content": "Generate feature-index.json (feature_mode only)", "status": "pending", "activeForm": "Building feature index"},
+  {"content": "Execute Spec Agent (generate specs + index + changelog)", "status": "pending", "activeForm": "Generating specs"},
+  {"content": "Conditional Review Agent", "status": "pending", "activeForm": "Reviewing specs"},
  {"content": "Update context package and metadata", "status": "pending", "activeForm": "Finalizing"}
 ]
 ```
@@ -173,7 +176,7 @@ ${feature_mode ? `3. load_feature_decomposition → Read Feature Decomposition t
 ]

 ${feature_mode ? `### feature_conflict_map (feature_mode only)
-Bridge artifact from Phase 3A to Phase 6. One entry per feature from Feature Decomposition.
+Bridge artifact from Phase 3A to Phase 5. One entry per feature from Feature Decomposition.

 {
  "F-001": {
@@ -221,7 +224,7 @@ Bridge artifact from Phase 3A to Phase 6. One entry per feature from Feature Dec
 // Store enhancement_recommendations for Phase 4
 const enhancement_recommendations = agent_output.enhancement_recommendations;

-// Store feature_conflict_map for Phase 6 (feature_mode only)
+// Store feature_conflict_map for Phase 5 Spec Agent (feature_mode only)
 const feature_conflict_map = feature_mode ? agent_output.feature_conflict_map : null;
 ```

@@ -311,85 +314,43 @@ for (let i = 0; i < clarifications.length; i += BATCH_SIZE) {
 **Quality Rules**:

 **MUST Include**:
- ✅ All questions in Chinese (用中文提问)
- ✅ 基于跨角色分析的具体发现
- ✅ 选项包含业务影响说明
- ✅ 解决实际的模糊点或冲突
+- All questions in Chinese (用中文提问)
+- 基于跨角色分析的具体发现
+- 选项包含业务影响说明
+- 解决实际的模糊点或冲突

 **MUST Avoid**:
- ❌ 与角色分析无关的通用问题
- ❌ 重复已在 artifacts 阶段确认的内容
- ❌ 过于细节的实现级问题
+- 与角色分析无关的通用问题
+- 重复已在 artifacts 阶段确认的内容
+- 过于细节的实现级问题

-#### Step 3: Build Update Plan
+#### Step 3: Build Spec Context

 ```javascript
-update_plan = {
-  "role1": {
-    "enhancements": ["EP-001", "EP-003"],
-    "clarifications": [
-      {"question": "...", "answer": "...", "category": "..."}
-    ]
-  },
-  "role2": {
-    "enhancements": ["EP-002"],
-    "clarifications": [...]
-  }
+// Unified context for Spec Agent (replaces per-role update_plan)
+spec_context = {
+  selected_enhancements: selected_eps,  // ["EP-001", "EP-002", ...]
+  enhancement_details: enhancements.filter(ep => selected_eps.includes(ep.id)),
+  clarification_answers: [
+    { question: "...", answer: "...", category: "..." }
+  ],
+  original_user_intent: intent
 }
 ```

-### Phase 5: Parallel Document Update Agents
+### Phase 5: Spec Generation & Conditional Review

-**Execute in parallel** (one agent per role):
+**Single Spec Agent generates all outputs sequentially, then self-evaluates complexity to decide whether to trigger Review Agent.**

-```javascript
-// Single message with multiple Task calls for parallelism
-Task(conceptual-planning-agent, `
-## Agent Mission
-Apply enhancements and clarifications to ${role} analysis
+**Skip condition (feature_mode = false)**: Spec Agent generates a single `synthesis-specification.md` instead of per-feature specs. Feature-index.json is skipped. All other logic (changelog, review) still applies.

-## Input
- role: ${role}
- analysis_path: ${brainstorm_dir}/${role}/analysis.md
- enhancements: ${role_enhancements}
- clarifications: ${role_clarifications}
- original_user_intent: ${intent}
-
-## Flow Control Steps
-1. load_current_analysis → Read analysis file
-2. add_clarifications_section → Insert Q&A section
-3. apply_enhancements → Integrate into relevant sections
-4. resolve_contradictions → Remove conflicts
-5. enforce_terminology → Align terminology
-6. validate_intent → Verify alignment with user intent
-7. write_updated_file → Save changes
-
-## Output
-Updated ${role}/analysis.md
-`)
-```
-
-**Agent Characteristics**:
- **Isolation**: Each agent updates exactly ONE role (parallel safe)
- **Dependencies**: Zero cross-agent dependencies
- **Validation**: All updates must align with original_user_intent
-
-### Phase 6: Parallel Feature Spec Generation [feature_mode only]
-
-**Skip condition**: If `feature_mode` is false, skip Phase 6 and Phase 6.5 entirely. Proceed directly to Phase 7.
-
-**Purpose**: Generate one consolidated feature specification per feature by aggregating all role perspectives.
-
-#### Step 1: Prepare Feature Spec Directory
+#### Step 1: Prepare Input

 ```javascript
 const feature_specs_dir = `${brainstorm_dir}/feature-specs`;
-// Ensure directory exists (create if not)
-```
+// Ensure directory exists (create if not) [feature_mode only]

-#### Step 2: Build Per-Feature Input Bundles
-
-```javascript
+// Build per-feature input bundles [feature_mode only]
 const feature_bundles = feature_list.map(feature => {
  const fid = feature.id;
  const slug = feature.slug;
@@ -411,34 +372,130 @@ const feature_bundles = feature_list.map(feature => {
 });
 ```

-#### Step 3: Execute Parallel Feature Spec Agents
-
-**Execute in parallel** (one agent per feature):
+#### Step 2: Execute Spec Agent

 ```javascript
 Task(conceptual-planning-agent, `
 ## Agent Mission
-Generate consolidated feature specification for ${feature.feature_id}: ${feature.feature_name}
-by aggregating all role-specific analyses with conflict resolution.
+Generate all feature specifications sequentially, produce feature-index.json and synthesis-changelog.md.
+After generation, self-evaluate complexity and output complexity_score.

 ## Input
- feature_id: ${feature.feature_id}
- feature_slug: ${feature.feature_slug}
- feature_name: ${feature.feature_name}
- feature_priority: ${feature.feature_priority}
- role_analysis_files: ${feature.role_analysis_files}
- conflict_map_entry: ${JSON.stringify(feature.conflict_map_entry)}
- output_path: ${feature.output_path}
- guidance_spec_feature_section: (Feature Decomposition row for this feature)
+- brainstorm_dir: ${brainstorm_dir}
+- feature_mode: ${feature_mode}
+- participating_roles: ${participating_roles}
+${feature_mode ? `- feature_bundles: ${JSON.stringify(feature_bundles)}
+- feature_conflict_map: ${JSON.stringify(feature_conflict_map)}` : `- role_analysis_paths: ${role_analysis_paths}`}
+- spec_context: ${JSON.stringify(spec_context)}
+- guidance_spec_path: ${brainstorm_dir}/guidance-specification.md

 ## Flow Control Steps
-1. load_role_analyses → Read all role-specific analysis files for this feature
-   (Each file ~1500-2000 words, total ~6.5K words for 3-4 roles)
-2. apply_conflict_map → Use conflict_map_entry to identify resolved/unresolved conflicts
-3. four_layer_aggregation → Apply aggregation rules (see below)
-4. generate_feature_spec → Write consolidated spec using template
-5. write_output → Save to output_path

+### Step 1: Load Context (once)
+1. Read guidance-specification.md
+2. Read spec_context (enhancements + clarifications + user intent)
+${feature_mode
+  ? '3. Load feature_conflict_map into working memory'
+  : '3. Read all role analysis files'}
+
+### Step 2: Generate Specs
+${feature_mode ? `
+For EACH feature in feature_bundles (sequentially):
+  a. Read role-specific analysis files for this feature
+     (Each file ~1500-2000 words, total ~6.5K words for 3-4 roles)
+  b. Apply conflict_map_entry to identify resolved/unresolved conflicts
+  c. Apply four-layer aggregation rules (see below)
+  d. Apply relevant enhancements from spec_context.enhancement_details
+  e. Incorporate relevant clarification answers from spec_context.clarification_answers
+  f. Generate feature spec using template (see below)
+  g. Write to feature_bundles[i].output_path
+
+**Cross-feature context**: Decisions made in earlier features carry forward.
+When a later feature references an earlier one, use the actual decision (not re-analyze).
+` : `
+Generate a single synthesis-specification.md:
+  a. Read all role analysis files
+  b. Apply cross-role conflict resolution
+  c. Incorporate selected enhancements and clarification answers
+  d. Write consolidated synthesis to ${brainstorm_dir}/synthesis-specification.md
+`}
+
+### Step 3: Generate feature-index.json [feature_mode only]
+
+${feature_mode ? `
+Collect all generated spec paths and build structured index:
+
+const feature_index = {
+  "version": "1.0",
+  "generated_at": new Date().toISOString(),
+  "session_id": "${session_id}",
+  "feature_mode": true,
+  "features": feature_bundles.map(fb => ({
+    "id": fb.feature_id,
+    "slug": fb.feature_slug,
+    "name": fb.feature_name,
+    "priority": fb.feature_priority,
+    "spec_path": "feature-specs/" + fb.feature_id + "-" + fb.feature_slug + ".md",
+    "contributing_roles": fb.contributing_roles,
+    "cross_cutting_refs": feature_conflict_map[fb.feature_id]
+      ? feature_conflict_map[fb.feature_id].cross_refs : []
+  })),
+  "cross_cutting_specs": participating_roles
+    .filter(role => fileExists(brainstorm_dir + "/" + role + "/analysis-cross-cutting.md"))
+    .map(role => role + "/analysis-cross-cutting.md")
+};
+
+Write feature-index.json to ${brainstorm_dir}/feature-index.json
+` : 'Skip this step.'}
+
+### Step 4: Generate synthesis-changelog.md
+
+Record all synthesis decisions as audit trail:
+
+Write to ${brainstorm_dir}/synthesis-changelog.md:
+
+---
+# Synthesis Changelog
+
+**Session**: ${session_id}
+**Generated**: {timestamp}
+
+## Enhancements Applied
+For each selected enhancement:
+- **{EP-ID}**: {title} — {how it was incorporated into which spec(s)}
+
+## Clarifications Resolved
+For each clarification answer:
+- **{Category}**: {question} → {answer} — {impact on specs}
+
+## Conflicts Resolved
+For each conflict in feature_conflict_map:
+- **{Feature ID} / {topic}**: {resolution} [{confidence}]
+
+## Unresolved Items
+List any [DECISION NEEDED] or [UNRESOLVED] items remaining in specs.
+---
+
+### Step 5: Self-Evaluate Complexity
+
+Compute complexity_score based on generation results:
+
+| Dimension | Low (0) | Medium (1) | High (2) |
+|-----------|---------|------------|----------|
+| Feature count | ≤2 | 3-4 | ≥5 |
+| UNRESOLVED conflicts | 0 | 1-2 | ≥3 |
+| Participating roles | ≤2 | 3-4 | ≥5 |
+| Cross-feature dependencies | 0 | 1-2 | ≥3 |
+
+Output complexity_score (0-8) at the end of agent response.
+
+## Output
+- Feature specs: ${feature_mode ? 'feature-specs/F-{id}-{slug}.md' : 'synthesis-specification.md'}
+${feature_mode ? '- feature-index.json' : ''}
+- synthesis-changelog.md
+- complexity_score: {number}
+
+${feature_mode ? `
 ## Four-Layer Aggregation Rules

 ### Layer 1: Direct Reference
@@ -461,13 +518,15 @@ by aggregating all role-specific analyses with conflict resolution.
 - Add explicit dependency notes with feature IDs
 - Document integration points with other features
 - Note shared constraints or patterns
+` : ''}

+${feature_mode ? `
 ## Feature Spec Template (7 Sections, target 1500-2500 words)

 ---
-# Feature Spec: ${feature.feature_id} - ${feature.feature_name}
+# Feature Spec: {feature_id} - {feature_name}

-**Priority**: ${feature.feature_priority}
+**Priority**: {feature_priority}
 **Contributing Roles**: [list of roles]
 **Status**: Draft (from synthesis)

@@ -512,7 +571,7 @@ For each decision:

 ## 6. Detailed Analysis References
 [Pointers back to role-specific analysis documents]
- @../{role}/analysis-${feature.feature_id}-${feature.feature_slug}.md for each contributing role
+- @../{role}/analysis-{feature_id}-{feature_slug}.md for each contributing role
 - @../guidance-specification.md#feature-decomposition

 ## 7. Cross-Feature Dependencies
@@ -523,128 +582,109 @@ For each decision:
 - **Integration points**: [Specific interfaces between features]
 ---

-## Completion Criteria
+## Feature Spec Completion Criteria
 - All 7 sections populated with aggregated content
 - Section 2 (Design Decisions) is the most detailed section (40%+ of word count)
 - All conflicts from conflict_map_entry addressed with resolutions
 - Cross-feature dependencies explicitly documented
 - Word count between 1500-2500
 - No placeholder text except [DECISION NEEDED] for genuinely unresolved items
+` : ''}
 `)
 ```

-**Agent Characteristics (Phase 6)**:
- **Isolation**: Each agent processes exactly ONE feature (parallel safe)
- **Dependencies**: Requires Phase 3A feature_conflict_map and Phase 5 updated role analyses
- **Input budget**: ~6.5K words per agent (3-4 role sub-docs + conflict map entry)
- **Output budget**: 1500-2500 words per feature spec
+#### Step 3: Conditional Review Agent

-### Phase 6.5: Feature Index Generation [feature_mode only]
+**Trigger**: `complexity_score >= 4` (from Spec Agent output)

-**Skip condition**: Same as Phase 6 - skip if `feature_mode` is false.
-
-**Purpose**: Collect all Phase 6 outputs and generate structured `feature-index.json`.
-
-#### Step 1: Collect Feature Spec Outputs
+**Skip**: If `complexity_score < 4`, proceed directly to Phase 6 Finalization.

 ```javascript
-const feature_spec_files = Glob(`${brainstorm_dir}/feature-specs/F-*-*.md`);
+if (complexity_score >= 4) {
+  Task(conceptual-planning-agent, `
+## Agent Mission
+Review all generated feature specs for cross-feature consistency and quality.
+Read ONLY the generated specs (not role analysis originals) to minimize context.

-const cross_cutting_specs = participating_roles
-  .map(role => `${brainstorm_dir}/${role}/analysis-cross-cutting.md`)
-  .filter(path => fileExists(path));
-```
+## Input
+- brainstorm_dir: ${brainstorm_dir}
+- feature_mode: ${feature_mode}
+${feature_mode
+  ? `- feature_spec_files: ${Glob(brainstorm_dir + '/feature-specs/F-*-*.md')}
+- feature_index_path: ${brainstorm_dir}/feature-index.json`
+  : `- synthesis_spec_path: ${brainstorm_dir}/synthesis-specification.md`}
+- changelog_path: ${brainstorm_dir}/synthesis-changelog.md

-#### Step 2: Generate feature-index.json
+## Review Checklist

-```javascript
-const feature_index = {
-  "version": "1.0",
-  "generated_at": new Date().toISOString(),
-  "session_id": session_id,
-  "feature_mode": true,
-  "features": feature_list.map(feature => {
-    const fid = feature.id;
-    const slug = feature.slug;
-    const spec_path = `feature-specs/${fid}-${slug}.md`;
-    const spec_exists = fileExists(`${brainstorm_dir}/${spec_path}`);
+### 1. Cross-Feature Consistency
+- Terminology: same concept uses same term across all specs
+- Decisions: no contradictory decisions between features
+- Technology choices: consistent stack across features

-    const contributing_roles = participating_roles.filter(role =>
-      fileExists(`${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`)
-    );
+### 2. Conflict Resolution Completeness
+- All [UNRESOLVED] items have [DECISION NEEDED] markers
+- All [RESOLVED] items state clear decision + rationale
+- No silent conflicts (same topic, different decisions in different specs)

-    const cross_cutting_refs = feature_conflict_map[fid]
-      ? feature_conflict_map[fid].cross_refs
-      : [];
+### 3. Dependency Bidirectionality
+- If F-001 "Depends on" F-003 → F-003 must have "Required by" F-001
+- Cross-refs in feature-index.json match spec Section 7

-    return {
-      "id": fid,
-      "slug": slug,
-      "name": feature.description,
-      "priority": feature.priority,
-      "spec_path": spec_exists ? spec_path : null,
-      "contributing_roles": contributing_roles,
-      "cross_cutting_refs": cross_cutting_refs
-    };
-  }),
-  "cross_cutting_specs": cross_cutting_specs.map(path =>
-    path.replace(brainstorm_dir + '/', '')
-  )
-};
+### 4. Enhancement & Clarification Coverage
+- All selected enhancements (from changelog) reflected in relevant specs
+- All clarification answers (from changelog) incorporated

-Write(
-  `${brainstorm_dir}/feature-index.json`,
-  JSON.stringify(feature_index, null, 2)
-);
-```
+## Action Protocol
+- **Minor issues** (typo, missing cross-ref, terminology inconsistency):
+  Fix directly in the spec file. Log fix in review_fixes[].
+- **Major issues** (contradictory decisions, missing section, unaddressed conflict):
+  Add [REVIEW-FLAG] annotation inline. Log in review_flags[].

-#### feature-index.json Schema
+## Output Format
+Append to synthesis-changelog.md:

-```json
-{
-  "version": "1.0",
-  "generated_at": "2026-02-11T10:00:00.000Z",
-  "session_id": "WFS-xxx",
-  "feature_mode": true,
-  "features": [
-    {
-      "id": "F-001",
-      "slug": "real-time-sync",
-      "name": "Real-time collaborative synchronization",
-      "priority": "High",
-      "spec_path": "feature-specs/F-001-real-time-sync.md",
-      "contributing_roles": ["system-architect", "ux-expert", "data-architect"],
-      "cross_cutting_refs": ["F-003 offline-mode depends on sync strategy"]
-    }
-  ],
-  "cross_cutting_specs": [
-    "system-architect/analysis-cross-cutting.md",
-    "ux-expert/analysis-cross-cutting.md"
-  ]
+## Review Results
+**Complexity Score**: {score}
+**Specs Reviewed**: {count}
+**Minor Fixes Applied**: {count}
+**Major Flags Raised**: {count}
+
+### Fixes Applied
+- {spec_file}: {description of fix}
+
+### Flags Raised
+- {spec_file}: [REVIEW-FLAG] {description of issue}
+`)
 }
 ```

-**Consumers**: `action-planning-agent` reads feature-index.json to generate task JSONs. `code-developer` loads individual feature specs as implementation context.
+**Review Agent Characteristics**:
+- **Input**: Only generated specs + changelog (NOT role analysis originals)
+- **Context budget**: ~10-15K words (much smaller than generation phase)
+- **Write permission**: Can modify spec files for minor fixes; uses [REVIEW-FLAG] for major issues
+- **Isolation**: Does not touch role analysis files or guidance-specification.md

-### Phase 7: Finalization
+### Phase 6: Finalization

 #### Step 1: Update Context Package

 ```javascript
 const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json")

-// Update guidance-specification if exists
-// Update synthesis-specification if exists
-// Re-read all role analysis files
 // Update metadata timestamps
+// Add spec paths

-// If feature_mode: add feature-index.json and feature-specs paths
 if (feature_mode) {
  context_pkg.feature_index_path = `${brainstorm_dir}/feature-index.json`;
  context_pkg.feature_specs_dir = `${brainstorm_dir}/feature-specs/`;
  context_pkg.feature_mode = true;
+} else {
+  context_pkg.synthesis_spec_path = `${brainstorm_dir}/synthesis-specification.md`;
 }

+context_pkg.changelog_path = `${brainstorm_dir}/synthesis-changelog.md`;
+
 Write(context_pkg_path, JSON.stringify(context_pkg))
 ```

@@ -654,22 +694,23 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
 {
  "phases": {
    "BRAINSTORM": {
-      "status": "clarification_completed",
-      "clarification_completed": true,
+      "status": "synthesis_completed",
      "completed_at": "timestamp",
      "participating_roles": ["..."],
-      "clarification_results": {
+      "synthesis_results": {
        "enhancements_applied": ["EP-001", "EP-002"],
        "questions_asked": 3,
        "categories_clarified": ["Architecture", "UX"],
-        "roles_updated": ["role1", "role2"]
+        "complexity_score": 5,
+        "review_triggered": true,
+        "review_fixes": 2,
+        "review_flags": 0
      },
      "feature_spec_results": {
        "feature_mode": true,
        "features_generated": ["F-001", "F-002", "F-003"],
        "feature_index_path": ".brainstorming/feature-index.json",
-        "feature_specs_dir": ".brainstorming/feature-specs/",
-        "conflict_map_generated": true
+        "feature_specs_dir": ".brainstorming/feature-specs/"
      },
      "quality_metrics": {
        "user_intent_alignment": "validated",
@@ -691,12 +732,16 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
 **Session**: {sessionId}
 **Enhancements Applied**: EP-001, EP-002, EP-003
 **Questions Answered**: 3/5
-**Roles Updated**: role1, role2, role3
+**Complexity Score**: {score}/8
+
+### Review Status
+{review_triggered ? "Review Agent executed: {fixes} fixes applied, {flags} flags raised" : "Skipped (complexity below threshold)"}

 ### Feature Specs (feature_mode only)
 **Feature Specs Generated**: F-001, F-002, F-003
 **Feature Index**: .brainstorming/feature-index.json
 **Spec Directory**: .brainstorming/feature-specs/
+**Changelog**: .brainstorming/synthesis-changelog.md

 ### Next Steps
 PROCEED: `/workflow:plan --session {session-id}`
@@ -704,77 +749,66 @@ PROCEED: `/workflow:plan --session {session-id}`

 ## Output

-**Location (role analyses)**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
+**Location (role analyses)**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md` (read-only, never modified by synthesis)
 **Location (feature specs)**: `.workflow/active/WFS-{session}/.brainstorming/feature-specs/F-{id}-{slug}.md` [feature_mode]
+**Location (synthesis spec)**: `.workflow/active/WFS-{session}/.brainstorming/synthesis-specification.md` [non-feature_mode]
 **Location (feature index)**: `.workflow/active/WFS-{session}/.brainstorming/feature-index.json` [feature_mode]
+**Location (changelog)**: `.workflow/active/WFS-{session}/.brainstorming/synthesis-changelog.md`

-**Updated Directory Structure** (feature_mode):
+**Directory Structure** (feature_mode):
 ```
 .workflow/active/WFS-{session}/.brainstorming/
-├── guidance-specification.md
-├── feature-index.json                    # Phase 6.5 output
-├── feature-specs/                        # Phase 6 output directory
-│   ├── F-001-{slug}.md                   # Consolidated feature spec (1500-2500 words)
+├── guidance-specification.md              # Phase 2 output (read-only)
+├── feature-index.json                     # Phase 5 Spec Agent output
+├── synthesis-changelog.md                 # Phase 5 Spec Agent output (+ Review appendix)
+├── feature-specs/                         # Phase 5 Spec Agent output
+│   ├── F-001-{slug}.md                    # Consolidated feature spec (1500-2500 words)
 │   ├── F-002-{slug}.md
 │   └── F-00N-{slug}.md
-├── {role-1}/
-│   ├── analysis.md                       # Role overview index (read by Phase 3A)
+├── {role-1}/                              # Phase 3 output (IMMUTABLE)
+│   ├── analysis.md                        # Role overview index
 │   ├── analysis-cross-cutting.md
-│   ├── analysis-F-001-{slug}.md          # Per-feature detail (read by Phase 6)
+│   ├── analysis-F-001-{slug}.md           # Per-feature detail
 │   └── analysis-F-002-{slug}.md
 └── {role-N}/
    └── ...
 ```

-**Updated Role Analysis Structure**:
-```markdown
-## Clarifications
-### Session {date}
- **Q**: {question} (Category: {category})
-  **A**: {answer}
-
-## {Existing Sections}
-{Refined content based on clarifications}
-```
-
-**Changes**:
- User intent validated/corrected
- Requirements more specific/measurable
- Architecture with rationale
- Ambiguities resolved, placeholders removed
- Consistent terminology
- Feature specs generated with cross-role conflict resolution [feature_mode]
- Feature index provides structured access for downstream consumers [feature_mode]
+**Consumers**: `action-planning-agent` reads feature-index.json to generate task JSONs. `code-developer` loads individual feature specs as implementation context.

 ## Quality Checklist

 **Content**:
- All role analyses loaded/analyzed
+- All role analyses loaded/analyzed (read-only)
 - Cross-role analysis (consensus, conflicts, gaps)
 - 9-category ambiguity scan
 - Questions prioritized

-**Analysis**:
- User intent validated
- Cross-role synthesis complete
- Ambiguities resolved
- Terminology consistent
-
-**Documents**:
- Clarifications section formatted
- Sections reflect answers
- No placeholders (TODO/TBD)
- Valid Markdown
+**Spec Generation**:
+- Single Spec Agent generates all specs sequentially
+- Cross-feature decisions carry forward (no re-analysis)
+- All selected enhancements incorporated
+- All clarification answers reflected
+- synthesis-changelog.md records all decisions

 **Feature Specs (feature_mode only)**:
 - Phase 3A reads only analysis.md index files (not sub-documents), input token <= 5K words
 - feature_conflict_map generated with consensus/conflicts/cross_refs per feature
- Phase 6 parallel agents defined: one per feature, input token <= 7K words each
 - Feature spec template has 7 sections, Section 2 (Design Decisions) is core
 - Four-layer aggregation rules applied
 - Each feature spec is 1500-2500 words
 - feature-index.json generated with features[] + cross_cutting_specs[]
- feature-specs/ directory created with F-{id}-{slug}.md files
+
+**Review (conditional)**:
+- complexity_score computed from 4 dimensions (0-8 scale)
+- Review triggered when score >= 4
+- Minor fixes applied directly, major issues flagged with [REVIEW-FLAG]
+- Review results appended to synthesis-changelog.md
+
+**Immutability**:
+- Role analysis files NOT modified by synthesis
+- guidance-specification.md NOT modified by synthesis
+- Only spec files, index, and changelog are write targets

 - **TodoWrite**: Mark Phase 4 completed, collapse all sub-tasks to summary