catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-28 09:23:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
catlog22
2026-02-17 10:37:41 +08:00
parent 8ac4356d63
commit b23e822a35
2 changed files with 280 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
.claude/skills/brainstorm/SKILL.md
View File

@@ -35,8 +35,8 @@ Artifacts N×Role Synthesis 1×Role
``` ```
Auto Mode: Auto Mode:
Phase 2 (artifacts) → guidance-specification.md + selected_roles[] Phase 2 (artifacts) → guidance-specification.md + selected_roles[]
→ Phase 3 (N × role-analysis) → {role}/analysis*.md → Phase 3 (N × role-analysis) → {role}/analysis*.md (immutable)
→ Phase 4 (synthesis) → feature-specs/ + feature-index.json → Phase 4 (synthesis) → feature-specs/ + feature-index.json + synthesis-changelog.md
Single Role Mode: Single Role Mode:
Phase 3 (1 × role-analysis) → {role}/analysis*.md 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 #### Phase 4: Synthesis Integration
Ref: phases/04-synthesis.md 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 **Input**: session_id from Phase 2, all role analysis files from Phase 3 (read-only)
**Output**: Updated analyses, feature-specs/, feature-index.json **Output**: feature-specs/, feature-index.json, synthesis-changelog.md
**TodoWrite**: Attach synthesis sub-tasks, execute sequentially, collapse on completion. **TodoWrite**: Attach synthesis sub-tasks, execute sequentially, collapse on completion.
@@ -222,13 +222,13 @@ Phase 3:
Input: selected_roles[], session_id Input: selected_roles[], session_id
guidance-specification.md guidance-specification.md
style_skill (for ui-designer) style_skill (for ui-designer)
Output: {role}/analysis*.md (N files) Output: {role}/analysis*.md (N files, immutable after this point)
↓ ↓
Phase 4: Phase 4:
Input: session_id, all analysis files Input: session_id, all analysis files (read-only)
Output: Updated analyses Output: feature-specs/F-{id}-{slug}.md
feature-specs/F-{id}-{slug}.md
feature-index.json feature-index.json
synthesis-changelog.md
``` ```
## TodoWrite Pattern ## TodoWrite Pattern
@@ -322,16 +322,17 @@ Initial → Phase 1 Mode Routing (completed)
│ └── context-package.json # Phase 0 output (auto mode) │ └── context-package.json # Phase 0 output (auto mode)
└── .brainstorming/ └── .brainstorming/
├── guidance-specification.md # Framework (Phase 2, auto mode) ├── guidance-specification.md # Framework (Phase 2, auto mode)
├── feature-index.json # Feature index (Phase 4, auto mode) ├── feature-index.json # Feature index (Phase 4, auto mode, feature_mode)
├── feature-specs/ # Feature specs (Phase 4, auto 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-001-{slug}.md
│ └── F-00N-{slug}.md │ └── F-00N-{slug}.md
├── {role}/ ├── {role}/ # Role analyses (IMMUTABLE after Phase 3)
│ ├── {role}-context.md # Interactive Q&A responses │ ├── {role}-context.md # Interactive Q&A responses
│ ├── analysis.md # Main/index document │ ├── analysis.md # Main/index document
│ ├── analysis-cross-cutting.md # Cross-feature (feature_mode) │ ├── analysis-cross-cutting.md # Cross-feature (feature_mode)
│ └── analysis-F-{id}-{slug}.md # Per-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 ## Error Handling

498
.claude/skills/brainstorm/phases/04-synthesis.md
View File

@@ -1,17 +1,23 @@
# Phase 4: Synthesis Integration # 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 ## 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 - Execute cross-role analysis to identify consensus, conflicts, and gaps
- Present enhancement recommendations and clarification questions to user - Present enhancement recommendations and clarification questions to user
- Update role analyses in parallel with enhancements and clarifications - Generate consolidated feature specifications as final synthesis artifact
- Generate consolidated feature specifications (feature_mode) - Conditional quality review based on task complexity
- Generate feature index for downstream consumers (feature_mode)
- Update context package and session metadata - 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 ## Auto Mode
When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions, use default answers. 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 | | 1 | Session detection | Main flow | session_id, brainstorm_dir |
| 2 | File discovery | Main flow | role_analysis_paths | | 2 | File discovery | Main flow | role_analysis_paths |
| 3A | Cross-role analysis | Agent | enhancement_recommendations, feature_conflict_map | | 3A | Cross-role analysis | Agent | enhancement_recommendations, feature_conflict_map |
| 4 | User interaction | Main flow + AskUserQuestion | update_plan | | 4 | User interaction | Main flow + AskUserQuestion | spec_context |
| 5 | Document updates | Parallel agents | Updated analysis*.md | | 5 | Spec generation + conditional review | Spec Agent → Review Agent | feature-specs/, feature-index.json, synthesis-changelog.md |
| 6 | Feature spec generation | Parallel agents | feature-specs/F-{id}-{slug}.md [feature_mode] | | 6 | Finalization | Main flow | context-package.json, report |
| 6.5 | Feature index generation | Main flow | feature-index.json [feature_mode] |
| 7 | Finalization | Main flow | context-package.json, report |
### AskUserQuestion Pattern ### AskUserQuestion Pattern
@@ -73,9 +77,8 @@ AskUserQuestion({
{"content": "Execute analysis agent (cross-role analysis + feature conflict map)", "status": "pending", "activeForm": "Executing analysis"}, {"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": "Present enhancements via AskUserQuestion", "status": "pending", "activeForm": "Selecting enhancements"},
{"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"}, {"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"},
{"content": "Execute parallel update agents", "status": "pending", "activeForm": "Updating documents"}, {"content": "Execute Spec Agent (generate specs + index + changelog)", "status": "pending", "activeForm": "Generating specs"},
{"content": "Generate parallel feature specs (feature_mode only)", "status": "pending", "activeForm": "Generating feature specs"}, {"content": "Conditional Review Agent", "status": "pending", "activeForm": "Reviewing specs"},
{"content": "Generate feature-index.json (feature_mode only)", "status": "pending", "activeForm": "Building feature index"},
{"content": "Update context package and metadata", "status": "pending", "activeForm": "Finalizing"} {"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) ${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": { "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 // Store enhancement_recommendations for Phase 4
const enhancement_recommendations = agent_output.enhancement_recommendations; 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; 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**: **Quality Rules**:
**MUST Include**: **MUST Include**:
- ✅ All questions in Chinese (用中文提问) - All questions in Chinese (用中文提问)
- ✅ 基于跨角色分析的具体发现 - 基于跨角色分析的具体发现
- ✅ 选项包含业务影响说明 - 选项包含业务影响说明
- ✅ 解决实际的模糊点或冲突 - 解决实际的模糊点或冲突
**MUST Avoid**: **MUST Avoid**:
- ❌ 与角色分析无关的通用问题 - 与角色分析无关的通用问题
- ❌ 重复已在 artifacts 阶段确认的内容 - 重复已在 artifacts 阶段确认的内容
- ❌ 过于细节的实现级问题 - 过于细节的实现级问题
#### Step 3: Build Update Plan #### Step 3: Build Spec Context
```javascript ```javascript
update_plan = { // Unified context for Spec Agent (replaces per-role update_plan)
"role1": { spec_context = {
"enhancements": ["EP-001", "EP-003"], selected_enhancements: selected_eps, // ["EP-001", "EP-002", ...]
"clarifications": [ enhancement_details: enhancements.filter(ep => selected_eps.includes(ep.id)),
{"question": "...", "answer": "...", "category": "..."} clarification_answers: [
] { question: "...", answer: "...", category: "..." }
}, ],
"role2": { original_user_intent: intent
"enhancements": ["EP-002"],
"clarifications": [...]
}
} }
``` ```
### 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 **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.
// Single message with multiple Task calls for parallelism
Task(conceptual-planning-agent, `
## Agent Mission
Apply enhancements and clarifications to ${role} analysis
## Input #### Step 1: Prepare 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
```javascript ```javascript
const feature_specs_dir = `${brainstorm_dir}/feature-specs`; 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 // Build per-feature input bundles [feature_mode only]
```javascript
const feature_bundles = feature_list.map(feature => { const feature_bundles = feature_list.map(feature => {
const fid = feature.id; const fid = feature.id;
const slug = feature.slug; const slug = feature.slug;
@@ -411,34 +372,130 @@ const feature_bundles = feature_list.map(feature => {
}); });
``` ```
#### Step 3: Execute Parallel Feature Spec Agents #### Step 2: Execute Spec Agent
**Execute in parallel** (one agent per feature):
```javascript ```javascript
Task(conceptual-planning-agent, ` Task(conceptual-planning-agent, `
## Agent Mission ## Agent Mission
Generate consolidated feature specification for ${feature.feature_id}: ${feature.feature_name} Generate all feature specifications sequentially, produce feature-index.json and synthesis-changelog.md.
by aggregating all role-specific analyses with conflict resolution. After generation, self-evaluate complexity and output complexity_score.
## Input ## Input
- feature_id: ${feature.feature_id} - brainstorm_dir: ${brainstorm_dir}
- feature_slug: ${feature.feature_slug} - feature_mode: ${feature_mode}
- feature_name: ${feature.feature_name} - participating_roles: ${participating_roles}
- feature_priority: ${feature.feature_priority} ${feature_mode ? `- feature_bundles: ${JSON.stringify(feature_bundles)}
- role_analysis_files: ${feature.role_analysis_files} - feature_conflict_map: ${JSON.stringify(feature_conflict_map)}` : `- role_analysis_paths: ${role_analysis_paths}`}
- conflict_map_entry: ${JSON.stringify(feature.conflict_map_entry)} - spec_context: ${JSON.stringify(spec_context)}
- output_path: ${feature.output_path} - guidance_spec_path: ${brainstorm_dir}/guidance-specification.md
- guidance_spec_feature_section: (Feature Decomposition row for this feature)
## Flow Control Steps ## 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 ## Four-Layer Aggregation Rules
### Layer 1: Direct Reference ### Layer 1: Direct Reference
@@ -461,13 +518,15 @@ by aggregating all role-specific analyses with conflict resolution.
- Add explicit dependency notes with feature IDs - Add explicit dependency notes with feature IDs
- Document integration points with other features - Document integration points with other features
- Note shared constraints or patterns - Note shared constraints or patterns
` : ''}
${feature_mode ? `
## Feature Spec Template (7 Sections, target 1500-2500 words) ## 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] **Contributing Roles**: [list of roles]
**Status**: Draft (from synthesis) **Status**: Draft (from synthesis)
@@ -512,7 +571,7 @@ For each decision:
## 6. Detailed Analysis References ## 6. Detailed Analysis References
[Pointers back to role-specific analysis documents] [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 - @../guidance-specification.md#feature-decomposition
## 7. Cross-Feature Dependencies ## 7. Cross-Feature Dependencies
@@ -523,128 +582,109 @@ For each decision:
- **Integration points**: [Specific interfaces between features] - **Integration points**: [Specific interfaces between features]
--- ---
## Completion Criteria ## Feature Spec Completion Criteria
- All 7 sections populated with aggregated content - All 7 sections populated with aggregated content
- Section 2 (Design Decisions) is the most detailed section (40%+ of word count) - Section 2 (Design Decisions) is the most detailed section (40%+ of word count)
- All conflicts from conflict_map_entry addressed with resolutions - All conflicts from conflict_map_entry addressed with resolutions
- Cross-feature dependencies explicitly documented - Cross-feature dependencies explicitly documented
- Word count between 1500-2500 - Word count between 1500-2500
- No placeholder text except [DECISION NEEDED] for genuinely unresolved items - No placeholder text except [DECISION NEEDED] for genuinely unresolved items
` : ''}
`) `)
``` ```
**Agent Characteristics (Phase 6)**: #### Step 3: Conditional Review Agent
- **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
### 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. **Skip**: If `complexity_score < 4`, proceed directly to Phase 6 Finalization.
**Purpose**: Collect all Phase 6 outputs and generate structured `feature-index.json`.
#### Step 1: Collect Feature Spec Outputs
```javascript ```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 ## Input
.map(role => `${brainstorm_dir}/${role}/analysis-cross-cutting.md`) - brainstorm_dir: ${brainstorm_dir}
.filter(path => fileExists(path)); - 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 ### 1. Cross-Feature Consistency
const feature_index = { - Terminology: same concept uses same term across all specs
"version": "1.0", - Decisions: no contradictory decisions between features
"generated_at": new Date().toISOString(), - Technology choices: consistent stack across features
"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}`);
const contributing_roles = participating_roles.filter(role => ### 2. Conflict Resolution Completeness
fileExists(`${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`) - 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] ### 3. Dependency Bidirectionality
? feature_conflict_map[fid].cross_refs - 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 { ### 4. Enhancement & Clarification Coverage
"id": fid, - All selected enhancements (from changelog) reflected in relevant specs
"slug": slug, - All clarification answers (from changelog) incorporated
"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 + '/', '')
)
};
Write( ## Action Protocol
`${brainstorm_dir}/feature-index.json`, - **Minor issues** (typo, missing cross-ref, terminology inconsistency):
JSON.stringify(feature_index, null, 2) 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 ## Review Results
{ **Complexity Score**: {score}
"version": "1.0", **Specs Reviewed**: {count}
"generated_at": "2026-02-11T10:00:00.000Z", **Minor Fixes Applied**: {count}
"session_id": "WFS-xxx", **Major Flags Raised**: {count}
"feature_mode": true,
"features": [ ### Fixes Applied
{ - {spec_file}: {description of fix}
"id": "F-001",
"slug": "real-time-sync", ### Flags Raised
"name": "Real-time collaborative synchronization", - {spec_file}: [REVIEW-FLAG] {description of issue}
"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"
]
} }
``` ```
**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 #### Step 1: Update Context Package
```javascript ```javascript
const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json") 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 // Update metadata timestamps
// Add spec paths
// If feature_mode: add feature-index.json and feature-specs paths
if (feature_mode) { if (feature_mode) {
context_pkg.feature_index_path = `${brainstorm_dir}/feature-index.json`; context_pkg.feature_index_path = `${brainstorm_dir}/feature-index.json`;
context_pkg.feature_specs_dir = `${brainstorm_dir}/feature-specs/`; context_pkg.feature_specs_dir = `${brainstorm_dir}/feature-specs/`;
context_pkg.feature_mode = true; 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)) Write(context_pkg_path, JSON.stringify(context_pkg))
``` ```
@@ -654,22 +694,23 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
{ {
"phases": { "phases": {
"BRAINSTORM": { "BRAINSTORM": {
"status": "clarification_completed", "status": "synthesis_completed",
"clarification_completed": true,
"completed_at": "timestamp", "completed_at": "timestamp",
"participating_roles": ["..."], "participating_roles": ["..."],
"clarification_results": { "synthesis_results": {
"enhancements_applied": ["EP-001", "EP-002"], "enhancements_applied": ["EP-001", "EP-002"],
"questions_asked": 3, "questions_asked": 3,
"categories_clarified": ["Architecture", "UX"], "categories_clarified": ["Architecture", "UX"],
"roles_updated": ["role1", "role2"] "complexity_score": 5,
"review_triggered": true,
"review_fixes": 2,
"review_flags": 0
}, },
"feature_spec_results": { "feature_spec_results": {
"feature_mode": true, "feature_mode": true,
"features_generated": ["F-001", "F-002", "F-003"], "features_generated": ["F-001", "F-002", "F-003"],
"feature_index_path": ".brainstorming/feature-index.json", "feature_index_path": ".brainstorming/feature-index.json",
"feature_specs_dir": ".brainstorming/feature-specs/", "feature_specs_dir": ".brainstorming/feature-specs/"
"conflict_map_generated": true
}, },
"quality_metrics": { "quality_metrics": {
"user_intent_alignment": "validated", "user_intent_alignment": "validated",
@@ -691,12 +732,16 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
**Session**: {sessionId} **Session**: {sessionId}
**Enhancements Applied**: EP-001, EP-002, EP-003 **Enhancements Applied**: EP-001, EP-002, EP-003
**Questions Answered**: 3/5 **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 (feature_mode only)
**Feature Specs Generated**: F-001, F-002, F-003 **Feature Specs Generated**: F-001, F-002, F-003
**Feature Index**: .brainstorming/feature-index.json **Feature Index**: .brainstorming/feature-index.json
**Spec Directory**: .brainstorming/feature-specs/ **Spec Directory**: .brainstorming/feature-specs/
**Changelog**: .brainstorming/synthesis-changelog.md
### Next Steps ### Next Steps
PROCEED: `/workflow:plan --session {session-id}` PROCEED: `/workflow:plan --session {session-id}`
@@ -704,77 +749,66 @@ PROCEED: `/workflow:plan --session {session-id}`
## Output ## 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 (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 (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/ .workflow/active/WFS-{session}/.brainstorming/
├── guidance-specification.md ├── guidance-specification.md # Phase 2 output (read-only)
├── feature-index.json # Phase 6.5 output ├── feature-index.json # Phase 5 Spec Agent output
├── feature-specs/ # Phase 6 output directory ├── synthesis-changelog.md # Phase 5 Spec Agent output (+ Review appendix)
│ ├── F-001-{slug}.md # Consolidated feature spec (1500-2500 words) ├── feature-specs/ # Phase 5 Spec Agent output
│ ├── F-001-{slug}.md # Consolidated feature spec (1500-2500 words)
│ ├── F-002-{slug}.md │ ├── F-002-{slug}.md
│ └── F-00N-{slug}.md │ └── F-00N-{slug}.md
├── {role-1}/ ├── {role-1}/ # Phase 3 output (IMMUTABLE)
│ ├── analysis.md # Role overview index (read by Phase 3A) │ ├── analysis.md # Role overview index
│ ├── analysis-cross-cutting.md │ ├── 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 │ └── analysis-F-002-{slug}.md
└── {role-N}/ └── {role-N}/
└── ... └── ...
``` ```
**Updated Role Analysis Structure**: **Consumers**: `action-planning-agent` reads feature-index.json to generate task JSONs. `code-developer` loads individual feature specs as implementation context.
```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]
## Quality Checklist ## Quality Checklist
**Content**: **Content**:
- All role analyses loaded/analyzed - All role analyses loaded/analyzed (read-only)
- Cross-role analysis (consensus, conflicts, gaps) - Cross-role analysis (consensus, conflicts, gaps)
- 9-category ambiguity scan - 9-category ambiguity scan
- Questions prioritized - Questions prioritized
**Analysis**: **Spec Generation**:
- User intent validated - Single Spec Agent generates all specs sequentially
- Cross-role synthesis complete - Cross-feature decisions carry forward (no re-analysis)
- Ambiguities resolved - All selected enhancements incorporated
- Terminology consistent - All clarification answers reflected
- synthesis-changelog.md records all decisions
**Documents**:
- Clarifications section formatted
- Sections reflect answers
- No placeholders (TODO/TBD)
- Valid Markdown
**Feature Specs (feature_mode only)**: **Feature Specs (feature_mode only)**:
- Phase 3A reads only analysis.md index files (not sub-documents), input token <= 5K words - 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 - 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 - Feature spec template has 7 sections, Section 2 (Design Decisions) is core
- Four-layer aggregation rules applied - Four-layer aggregation rules applied
- Each feature spec is 1500-2500 words - Each feature spec is 1500-2500 words
- feature-index.json generated with features[] + cross_cutting_specs[] - 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 - **TodoWrite**: Mark Phase 4 completed, collapse all sub-tasks to summary