compound-capture

compound-capture Skill

Purpose: Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).

Headless Mode Detection

If $ARGUMENTS contains --headless, set HEADLESS_MODE=true. Strip --headless from $ARGUMENTS before processing remaining args. Headless mode affects Steps 2, 3, 5, 8, and auto-consolidation Step E.

Overview

This skill captures problem solutions immediately after confirmation, creating structured documentation that serves as a searchable knowledge base for future sessions.

Organization: Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., knowledge-base/project/learnings/performance-issues/n-plus-one-briefs.md). Files use YAML frontmatter for metadata and searchability.

<critical_sequence name="documentation-capture" enforce_order="strict">

Documentation Capture Process

<step number="1" required="true">

Step 1: Detect Confirmation

Auto-invoke after phrases:

• "that worked"
• "it's fixed"
• "working now"
• "problem solved"
• "that did it"

OR manual: /doc-fix command

Non-trivial problems only:

• Multiple investigation attempts needed
• Tricky debugging that took time
• Non-obvious solution
• Future sessions would benefit

Skip documentation for:

• Simple typos
• Obvious syntax errors
• Trivial fixes immediately corrected

</step>

<step number="2" required="true" depends_on="1">

Step 2: Gather Context

Extract from conversation history:

Check for session-state.md: Run git branch --show-current. If on a feat-* branch, check if knowledge-base/project/specs/feat-<name>/session-state.md exists. If it does, read it and incorporate forwarded errors from ### Errors and decisions from ### Decisions into the context below. These came from preceding pipeline phases whose context was compacted.

Required information:

• Module name: Which module or component had the problem
• Symptom: Observable error/behavior (exact error messages)
• Investigation attempts: What didn't work and why
• Root cause: Technical explanation of actual problem
• Solution: What fixed it (code/config changes)
• Prevention: How to avoid in future

Session errors (beyond the target problem):

Scan conversation history AND session-state.md (if present) for errors unrelated to the main problem investigation documented above. Only capture errors that are NOT part of the investigation attempts. Skip trivial errors immediately corrected (typos in commands, expected test failures during TDD).

Extract for each error found:

• Describe what went wrong (1 sentence)
• Note what was done to recover
• Suggest how to prevent it in future sessions (1 sentence)

If no session errors are found, output "Session errors: none detected" (do not skip silently — the explicit acknowledgment prevents the model from accidentally dropping errors by judging the session as clean).

Environment details:

• Rails version
• Stage (0-6 or post-implementation)
• OS version
• File/line references

BLOCKING REQUIREMENT: If critical context is missing (module name, exact error, stage, or resolution steps):

Headless mode: Infer missing fields from session context (conversation history, session-state.md, git log). Skip any field that cannot be reasonably inferred — do not prompt. Proceed to Step 3 with whatever context is available.

Interactive mode: Ask user and WAIT for response before proceeding to Step 3:

I need a few details to document this properly:

1. Which module had this issue? [ModuleName]
2. What was the exact error message or symptom?
3. What stage were you in? (0-6 or post-implementation)

[Continue after user provides details]

</step>

<step number="3" required="false" depends_on="2">

Step 3: Check Existing Docs

Search knowledge-base/project/learnings/ for similar issues. Prefer faceted search when the current learning carries a specific tags: or category: value — facet filters cut noise before grep runs and keep related-doc lookups focused:

# Faceted (preferred when the learning has a tag or category)
/kb-search --tag eager-loading
/kb-search --category performance-issues n+1

Fall back to raw grep when no facet fits or the facet artifact is missing:

# Keyword grep (fallback)
grep -r "exact error phrase" knowledge-base/project/learnings/

# Symptom category browse
ls knowledge-base/project/learnings/[category]/

Valid tag/category values are listed in knowledge-base/kb-tags.txt and knowledge-base/kb-categories.txt (regenerated by running bash scripts/generate-kb-index.sh).

IF similar issue found:

Headless mode: Auto-select "Create new doc with cross-reference" without prompting.

Interactive mode: Present decision options:

Found similar issue: knowledge-base/project/learnings/[path]

What's next?
1. Create new doc with cross-reference (recommended)
2. Update existing doc (only if same root cause)
3. Other

Choose (1-3): _

WAIT for user response, then execute chosen action.

ELSE (no similar issue found):

Proceed directly to Step 4 (no user interaction needed). </step>

<step number="4" required="true" depends_on="2">

Step 4: Generate Filename

Format: [sanitized-symptom]-[module]-[YYYYMMDD].md

Sanitization rules:

• Lowercase
• Replace spaces with hyphens
• Remove special characters except hyphens
• Truncate to reasonable length (< 80 chars)

Examples:

• missing-include-BriefSystem-20251110.md
• parameter-not-saving-state-EmailProcessing-20251110.md
• webview-crash-on-resize-Assistant-20251110.md

</step>

<step number="5" required="true" depends_on="4" blocking="true">

Step 5: Validate YAML Schema

CRITICAL: All docs require validated YAML frontmatter with enum validation.

<validation_gate name="yaml-schema" blocking="true">

Validate against schema: Load schema.yaml and classify the problem against the enum values defined in [yaml-schema.md](./references/yaml-schema.md). Ensure all required fields are present and match allowed values exactly.

BLOCK if validation fails:

❌ YAML validation failed

Errors:
- problem_type: must be one of schema enums, got "compilation_error"
- severity: must be one of [critical, high, medium, low], got "invalid"
- symptoms: must be array with 1-5 items, got string

Please provide corrected values.

GATE ENFORCEMENT: Do NOT proceed to Step 6 (Create Documentation) until YAML frontmatter passes all validation rules defined in schema.yaml.

Headless mode exception: If HEADLESS_MODE=true and YAML validation fails after auto-correction attempts, skip the problematic learning and continue with remaining work. Log the skipped learning for manual review.

</validation_gate> </step>

<step number="6" required="true" depends_on="5">

Step 6: Create Documentation

Determine category from problem_type: Use the category mapping defined in [yaml-schema.md](./references/yaml-schema.md) (lines 49-61).

Create documentation file:

Determine the category from the validated YAML problem_type field and generate a filename. Then:

1. Create the category directory: mkdir -p knowledge-base/project/learnings/<category>
2. Write the documentation file to knowledge-base/project/learnings/<category>/<filename>.md using the template from [resolution-template.md](./assets/resolution-template.md)

Replace <category> with the mapped category and <filename> with the generated filename.

Result:

• Single file in category directory
• Enum validation ensures consistent categorization

Create documentation: Populate the structure from [resolution-template.md](./assets/resolution-template.md) with context gathered in Step 2 and validated YAML frontmatter from Step 5. </step>

<step number="7" required="false" depends_on="6">

Step 7: Cross-Refe