From d66064024cfdb0691fcc454ee0b654ad4c505197 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 29 Nov 2025 10:38:04 +0800 Subject: [PATCH] refactor: Optimize context-gather workflow with Synthesis role clarification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename Track 0 from 'Exploration Aggregation' to 'Exploration Synthesis' - Add explicit synthesis logic for critical_files prioritization and deduplication - Enhance explore-json-schema to support relevance scores in relevant_files - Update explore agent prompts across context-gather and lite-plan commands - Add synthesizeCriticalFiles and synthesizeConflictIndicators helper functions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/agents/context-search-agent.md | 44 ++++++++++++++++--- .claude/commands/workflow/lite-plan.md | 5 ++- .../commands/workflow/tools/context-gather.md | 9 ++-- .../reference/commands/workflow/lite-plan.md | 5 ++- .../schemas/explore-json-schema.json | 17 ++++++- 5 files changed, 67 insertions(+), 13 deletions(-) diff --git a/.claude/agents/context-search-agent.md b/.claude/agents/context-search-agent.md index facc83af..9f050aa3 100644 --- a/.claude/agents/context-search-agent.md +++ b/.claude/agents/context-search-agent.md @@ -104,10 +104,12 @@ Execute all tracks in parallel for comprehensive coverage. **Note**: Historical archive analysis (querying `.workflow/archives/manifest.json`) is optional and should be performed if the manifest exists. Inject findings into `conflict_detection.historical_conflicts[]`. -#### Track 0: Exploration Aggregation (Optional) +#### Track 0: Exploration Synthesis (Optional) **Trigger**: When `explorations-manifest.json` exists in session `.process/` folder +**Purpose**: Transform raw exploration data into prioritized, deduplicated insights. This is NOT simple aggregation - it synthesizes `critical_files` (priority-ranked), deduplicates patterns/integration_points, and generates `conflict_indicators`. + ```javascript // Check for exploration results from context-gather parallel explore phase const manifestPath = `.workflow/active/${session_id}/.process/explorations-manifest.json`; @@ -133,14 +135,28 @@ if (file_exists(manifestPath)) { } })); - // Aggregate insights across all explorations (fixed data access) + // SYNTHESIS (not aggregation): Transform raw data into prioritized insights const aggregated_insights = { - critical_files: deduplicateByRelevance(explorationData.flatMap(e => e.data.relevant_files || [])), - conflict_indicators: explorationData.flatMap(e => extractConflictIndicators(e.data, e.angle)), + // CRITICAL: Synthesize priority-ranked critical_files from multiple relevant_files lists + // - Deduplicate by path + // - Rank by: mention count across angles + individual relevance scores + // - Top 10-15 files only (focused, actionable) + critical_files: synthesizeCriticalFiles(explorationData.flatMap(e => e.data.relevant_files || [])), + + // SYNTHESIS: Generate conflict indicators from pattern mismatches, constraint violations + conflict_indicators: synthesizeConflictIndicators(explorationData), + + // Deduplicate clarification questions (merge similar questions) clarification_needs: deduplicateQuestions(explorationData.flatMap(e => e.data.clarification_needs || [])), + + // Preserve source attribution for traceability constraints: explorationData.map(e => ({ constraint: e.data.constraints, source_angle: e.angle })).filter(c => c.constraint), - all_patterns: explorationData.map(e => ({ patterns: e.data.patterns, source_angle: e.angle })), - all_integration_points: explorationData.map(e => ({ points: e.data.integration_points, source_angle: e.angle })) + + // Deduplicate patterns across angles (merge identical patterns) + all_patterns: deduplicatePatterns(explorationData.map(e => ({ patterns: e.data.patterns, source_angle: e.angle }))), + + // Deduplicate integration points (merge by file:line location) + all_integration_points: deduplicateIntegrationPoints(explorationData.map(e => ({ points: e.data.integration_points, source_angle: e.angle }))) }; // Store for Phase 3 packaging @@ -148,6 +164,22 @@ if (file_exists(manifestPath)) { complexity: manifest.complexity, angles: manifest.angles_explored, explorations, aggregated_insights }; } + +// Synthesis helper functions (conceptual) +function synthesizeCriticalFiles(allRelevantFiles) { + // 1. Group by path + // 2. Count mentions across angles + // 3. Average relevance scores + // 4. Rank by: (mention_count * 0.6) + (avg_relevance * 0.4) + // 5. Return top 10-15 with mentioned_by_angles attribution +} + +function synthesizeConflictIndicators(explorationData) { + // 1. Detect pattern mismatches across angles + // 2. Identify constraint violations + // 3. Flag files mentioned with conflicting integration approaches + // 4. Assign severity: critical/high/medium/low +} ``` #### Track 1: Reference Documentation diff --git a/.claude/commands/workflow/lite-plan.md b/.claude/commands/workflow/lite-plan.md index 81df4cc8..a42c0407 100644 --- a/.claude/commands/workflow/lite-plan.md +++ b/.claude/commands/workflow/lite-plan.md @@ -196,9 +196,12 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro **Required Fields** (all ${angle} focused): - project_structure: Modules/architecture relevant to ${angle} - relevant_files: Files affected from ${angle} perspective + **IMPORTANT**: Use object format with relevance scores for synthesis: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\` + Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low - patterns: ${angle}-related patterns to follow - dependencies: Dependencies relevant to ${angle} -- integration_points: Where to integrate from ${angle} viewpoint +- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations) - constraints: ${angle}-specific limitations/conventions - clarification_needs: ${angle}-related ambiguities (with options array) - _metadata.exploration_angle: "${angle}" diff --git a/.claude/commands/workflow/tools/context-gather.md b/.claude/commands/workflow/tools/context-gather.md index 24ace592..b34e53d7 100644 --- a/.claude/commands/workflow/tools/context-gather.md +++ b/.claude/commands/workflow/tools/context-gather.md @@ -46,7 +46,7 @@ Step 2: Complexity Assessment & Parallel Explore (NEW) Step 3: Invoke Context-Search Agent (with exploration input) ├─ Phase 1: Initialization & Pre-Analysis ├─ Phase 2: Multi-Source Discovery - │ ├─ Track 0: Exploration aggregation (NEW) + │ ├─ Track 0: Exploration Synthesis (prioritize & deduplicate) │ ├─ Track 1-4: Existing tracks └─ Phase 3: Synthesis & Packaging └─ Generate context-package.json with exploration_results @@ -164,9 +164,12 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro **Required Fields** (all ${angle} focused): - project_structure: Modules/architecture relevant to ${angle} - relevant_files: Files affected from ${angle} perspective + **IMPORTANT**: Use object format with relevance scores for synthesis: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\` + Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low - patterns: ${angle}-related patterns to follow - dependencies: Dependencies relevant to ${angle} -- integration_points: Where to integrate from ${angle} viewpoint +- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations) - constraints: ${angle}-specific limitations/conventions - clarification_needs: ${angle}-related ambiguities (with options array) - _metadata.exploration_angle: "${angle}" @@ -239,7 +242,7 @@ Execute complete context-search-agent workflow for implementation planning: ### Phase 2: Multi-Source Context Discovery Execute all discovery tracks: -- **Track 0**: Exploration aggregation (load ${sessionFolder}/explorations-manifest.json and aggregate) +- **Track 0**: Exploration Synthesis (load ${sessionFolder}/explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points) - **Track 1**: Historical archive analysis (query manifest.json for lessons learned) - **Track 2**: Reference documentation (CLAUDE.md, architecture docs) - **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs) diff --git a/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md b/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md index 81df4cc8..a42c0407 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md +++ b/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md @@ -196,9 +196,12 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro **Required Fields** (all ${angle} focused): - project_structure: Modules/architecture relevant to ${angle} - relevant_files: Files affected from ${angle} perspective + **IMPORTANT**: Use object format with relevance scores for synthesis: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\` + Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low - patterns: ${angle}-related patterns to follow - dependencies: Dependencies relevant to ${angle} -- integration_points: Where to integrate from ${angle} viewpoint +- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations) - constraints: ${angle}-specific limitations/conventions - clarification_needs: ${angle}-related ambiguities (with options array) - _metadata.exploration_angle: "${angle}" diff --git a/.claude/workflows/cli-templates/schemas/explore-json-schema.json b/.claude/workflows/cli-templates/schemas/explore-json-schema.json index ce0f91ef..7855b7a5 100644 --- a/.claude/workflows/cli-templates/schemas/explore-json-schema.json +++ b/.claude/workflows/cli-templates/schemas/explore-json-schema.json @@ -20,8 +20,21 @@ }, "relevant_files": { "type": "array", - "items": {"type": "string"}, - "description": "File paths to be modified or referenced for the task" + "items": { + "oneOf": [ + {"type": "string"}, + { + "type": "object", + "required": ["path", "relevance"], + "properties": { + "path": {"type": "string", "description": "File path relative to project root"}, + "relevance": {"type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"}, + "rationale": {"type": "string", "description": "Brief explanation of why this file is relevant from this exploration angle"} + } + } + ] + }, + "description": "File paths to be modified or referenced for the task. Prefer object format with relevance scores for synthesis prioritization." }, "patterns": { "type": "string",