everyinc__compound-engineering-plugin/plugins/compound-engineering/commands/workflows/compound.md

name, description, argument-hint

name	description	argument-hint
workflows:compound	Document a recently solved problem to compound your team's knowledge	[optional: brief context about the fix]

/compound

Coordinate multiple subagents working in parallel to document a recently solved problem.

Purpose

Captures problem solutions while context is fresh, creating structured documentation in docs/solutions/ with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.

Why "compound"? Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.

Usage

/workflows:compound                    # Document the most recent fix
/workflows:compound [brief context]    # Provide additional context hint

Execution Strategy: Two-Phase Orchestration

<critical_requirement> Only ONE file gets written - the final documentation.

Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file. </critical_requirement>

Phase 1: Parallel Research

<parallel_tasks>

Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.

1. Context Analyzer

• Extracts conversation history
• Identifies problem type, component, symptoms
• Validates against schema
• Returns: YAML frontmatter skeleton

2. Solution Extractor

• Analyzes all investigation steps
• Identifies root cause
• Extracts working solution with code examples
• Returns: Solution content block

3. Related Docs Finder

• Searches docs/solutions/ for related documentation
• Identifies cross-references and links
• Finds related GitHub issues
• Returns: Links and relationships

4. Prevention Strategist

• Develops prevention strategies
• Creates best practices guidance
• Generates test cases if applicable
• Returns: Prevention/testing content

5. Category Classifier

• Determines optimal docs/solutions/ category
• Validates category against schema
• Suggests filename based on slug
• Returns: Final path and filename

</parallel_tasks>

Phase 2: Assembly & Write

<sequential_tasks>

WAIT for all Phase 1 subagents to complete before proceeding.

The orchestrating agent (main conversation) performs these steps:

1. Collect all text results from Phase 1 subagents
2. Assemble complete markdown file from the collected pieces
3. Validate YAML frontmatter against schema
4. Create directory if needed: mkdir -p docs/solutions/[category]/
5. Write the SINGLE final file: docs/solutions/[category]/[filename].md

</sequential_tasks>

Phase 3: Optional Enhancement

WAIT for Phase 2 to complete before proceeding.

<parallel_tasks>

Based on problem type, optionally invoke specialized agents to review the documentation:

• performance_issue → performance-oracle
• security_issue → security-sentinel
• database_issue → data-integrity-guardian
• test_failure → cora-test-reviewer
• Any code-heavy issue → kieran-rails-reviewer + code-simplicity-reviewer

</parallel_tasks>

What It Captures

• Problem symptom: Exact error messages, observable behavior
• Investigation steps tried: What didn't work and why
• Root cause analysis: Technical explanation
• Working solution: Step-by-step fix with code examples
• Prevention strategies: How to avoid in future
• Cross-references: Links to related issues and docs

Preconditions

Problem has been solved (not in-progress) Solution has been verified working Non-trivial problem (not simple typo or obvious error)

What It Creates

Organized documentation:

• File: docs/solutions/[category]/[filename].md

Categories auto-detected from problem:

• build-errors/
• test-failures/
• runtime-errors/
• performance-issues/
• database-issues/
• security-issues/
• ui-bugs/
• integration-issues/
• logic-errors/

Common Mistakes to Avoid

❌ Wrong	✅ Correct
Subagents write files like context-analysis.md, solution-draft.md	Subagents return text data; orchestrator writes one final file
Research and assembly run in parallel	Research completes → then assembly runs
Multiple files created during workflow	Single file: docs/solutions/[category]/[filename].md

Success Output

✓ Documentation complete

Subagent Results:
  ✓ Context Analyzer: Identified performance_issue in brief_system
  ✓ Solution Extractor: 3 code fixes
  ✓ Related Docs Finder: 2 related issues
  ✓ Prevention Strategist: Prevention strategies, test suggestions
  ✓ Category Classifier: `performance-issues`

Specialized Agent Reviews (Auto-Triggered):
  ✓ performance-oracle: Validated query optimization approach
  ✓ kieran-rails-reviewer: Code examples meet Rails standards
  ✓ code-simplicity-reviewer: Solution is appropriately minimal
  ✓ every-style-editor: Documentation style verified

File created:
- docs/solutions/performance-issues/n-plus-one-brief-generation.md

This documentation will be searchable for future reference when similar
issues occur in the Email Processing or Brief System modules.

Next step:
Proceed to the `compound-docs` decision gate, which is the authoritative
post-capture menu for continuation, required reading promotion, convention
promotion, and tech debt tracking.

The Compounding Philosophy

This creates a compounding knowledge system:

1. First time you solve "N+1 query in brief generation" → Research (30 min)
2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
3. Next time similar issue occurs → Quick lookup (2 min)
4. Knowledge compounds → Team gets smarter

The feedback loop:

Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
    ↑                                                                      ↓
    └──────────────────────────────────────────────────────────────────────┘

Each unit of engineering work should make subsequent units of work easier—not harder.

Auto-Invoke

<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>

<manual_override> Use /workflows:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>

Routes To

compound-docs skill

Applicable Specialized Agents

Based on problem type, these agents can enhance documentation:

Code Quality & Review

• kieran-rails-reviewer: Reviews code examples for Rails best practices
• code-simplicity-reviewer: Ensures solution code is minimal and clear
• pattern-recognition-specialist: Identifies anti-patterns or repeating issues

Specific Domain Experts

• performance-oracle: Analyzes performance_issue category solutions
• security-sentinel: Reviews security_issue solutions for vulnerabilities
• cora-test-reviewer: Creates test cases for prevention strategies
• data-integrity-guardian: Reviews database_issue migrations and queries

Enhancement & Documentation

• best-practices-researcher: Enriches solution with industry best practices
• every-style-editor: Reviews documentation style and clarity
• framework-docs-researcher: Links to Rails/gem documentation references

When to Invoke

• Auto-triggered (optional): Agents can run post-documentation for enhancement
• Manual trigger: User can invoke agents after /workflows:compound completes for deeper review
• Customize agents: Edit compound-engineering.local.md or invoke the setup skill to configure which review agents are used across all workflows

Related Commands

• /research [topic] - Deep investigation (searches docs/solutions/ for patterns)
• /workflows:plan - Planning workflow (references documented solutions)