fix: consolidate compound-docs into ce-compound skill (#390)
This commit is contained in:
Trevin Chow
@@ -74,7 +74,6 @@ The primary entry points for engineering work, invoked as slash commands:
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `compound-docs` | Capture solved problems as categorized documentation |
|
||||
| `every-style-editor` | Review copy for Every's style guide compliance |
|
||||
| `proof` | Create, edit, and share documents via Proof collaborative editor |
|
||||
| `todo-create` | File-based todo tracking system |
|
||||
|
||||
@@ -43,7 +43,7 @@ Before going online, check if curated knowledge already exists in skills:
|
||||
- Frontend/Design → `frontend-design`, `swiss-design`
|
||||
- TypeScript/React → `react-best-practices`
|
||||
- AI/Agents → `agent-native-architecture`
|
||||
- Documentation → `compound-docs`, `every-style-editor`
|
||||
- Documentation → `ce:compound`, `every-style-editor`
|
||||
- File operations → `rclone`, `git-worktree`
|
||||
- Image generation → `gemini-imagegen`
|
||||
|
||||
|
||||
@@ -153,7 +153,10 @@ For each relevant document, return a summary in this format:
|
||||
|
||||
## Frontmatter Schema Reference
|
||||
|
||||
Reference the [yaml-schema.md](../../skills/compound-docs/references/yaml-schema.md) for the complete schema. Key enum values:
|
||||
Use this on-demand schema reference when you need the full contract:
|
||||
`../../skills/ce-compound/references/yaml-schema.md`
|
||||
|
||||
Key enum values:
|
||||
|
||||
**problem_type values:**
|
||||
- build_error, test_failure, runtime_error, performance_issue
|
||||
|
||||
@@ -503,13 +503,22 @@ If a doc cluster has 3+ overlapping docs, process pairwise: consolidate the two
|
||||
|
||||
Process Replace candidates **one at a time, sequentially**. Each replacement is written by a subagent to protect the main context window.
|
||||
|
||||
When a replacement is needed, read the documentation contract files and pass their contents into the replacement subagent's task prompt:
|
||||
|
||||
- `references/schema.yaml` — frontmatter fields and enum values
|
||||
- `references/yaml-schema.md` — category mapping
|
||||
- `assets/resolution-template.md` — section structure
|
||||
|
||||
Do not let replacement subagents invent frontmatter fields, enum values, or section order from memory.
|
||||
|
||||
**When evidence is sufficient:**
|
||||
|
||||
1. Spawn a single subagent to write the replacement learning. Pass it:
|
||||
- The old learning's full content
|
||||
- A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
|
||||
- The target path and category (same category as the old learning unless the category itself changed)
|
||||
2. The subagent writes the new learning following `ce:compound`'s document format: YAML frontmatter (title, category, date, module, component, tags), problem description, root cause, current solution with code examples, and prevention tips. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
|
||||
- The relevant contents of the three support files listed above
|
||||
2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
|
||||
3. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include `supersedes: [old learning filename]` for traceability, but this is optional — the git history and commit message provide the same information.
|
||||
|
||||
**When evidence is insufficient:**
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: [Clear problem title]
|
||||
date: [YYYY-MM-DD]
|
||||
category: [docs/solutions subdirectory]
|
||||
module: [Module or area]
|
||||
problem_type: [schema enum]
|
||||
component: [schema enum]
|
||||
symptoms:
|
||||
- [Observable symptom 1]
|
||||
root_cause: [schema enum]
|
||||
resolution_type: [schema enum]
|
||||
severity: [schema enum]
|
||||
tags: [keyword-one, keyword-two]
|
||||
---
|
||||
|
||||
# [Clear problem title]
|
||||
|
||||
## Problem
|
||||
[1-2 sentence description of the issue and user-visible impact]
|
||||
|
||||
## Symptoms
|
||||
- [Observable symptom or error]
|
||||
|
||||
## What Didn't Work
|
||||
- [Attempted fix and why it failed]
|
||||
|
||||
## Solution
|
||||
[The fix that worked, including code snippets when useful]
|
||||
|
||||
## Why This Works
|
||||
[Root cause explanation and why the fix addresses it]
|
||||
|
||||
## Prevention
|
||||
- [Concrete practice, test, or guardrail]
|
||||
|
||||
## Related Issues
|
||||
- [Related docs or issues, if any]
|
||||
@@ -0,0 +1,127 @@
|
||||
# Documentation schema for learnings written by ce:compound
|
||||
# Treat this as the canonical frontmatter contract for docs/solutions/.
|
||||
|
||||
required_fields:
|
||||
module:
|
||||
type: string
|
||||
description: "Module or area affected by the problem"
|
||||
|
||||
date:
|
||||
type: string
|
||||
pattern: '^\d{4}-\d{2}-\d{2}$'
|
||||
description: "Date the problem was solved (YYYY-MM-DD)"
|
||||
|
||||
problem_type:
|
||||
type: enum
|
||||
values:
|
||||
- build_error
|
||||
- test_failure
|
||||
- runtime_error
|
||||
- performance_issue
|
||||
- database_issue
|
||||
- security_issue
|
||||
- ui_bug
|
||||
- integration_issue
|
||||
- logic_error
|
||||
- developer_experience
|
||||
- workflow_issue
|
||||
- best_practice
|
||||
- documentation_gap
|
||||
description: "Primary category of the problem"
|
||||
|
||||
component:
|
||||
type: enum
|
||||
values:
|
||||
- rails_model
|
||||
- rails_controller
|
||||
- rails_view
|
||||
- service_object
|
||||
- background_job
|
||||
- database
|
||||
- frontend_stimulus
|
||||
- hotwire_turbo
|
||||
- email_processing
|
||||
- brief_system
|
||||
- assistant
|
||||
- authentication
|
||||
- payments
|
||||
- development_workflow
|
||||
- testing_framework
|
||||
- documentation
|
||||
- tooling
|
||||
description: "Component involved"
|
||||
|
||||
symptoms:
|
||||
type: array[string]
|
||||
min_items: 1
|
||||
max_items: 5
|
||||
description: "Observable symptoms such as errors or broken behavior"
|
||||
|
||||
root_cause:
|
||||
type: enum
|
||||
values:
|
||||
- missing_association
|
||||
- missing_include
|
||||
- missing_index
|
||||
- wrong_api
|
||||
- scope_issue
|
||||
- thread_violation
|
||||
- async_timing
|
||||
- memory_leak
|
||||
- config_error
|
||||
- logic_error
|
||||
- test_isolation
|
||||
- missing_validation
|
||||
- missing_permission
|
||||
- missing_workflow_step
|
||||
- inadequate_documentation
|
||||
- missing_tooling
|
||||
- incomplete_setup
|
||||
description: "Fundamental technical cause of the problem"
|
||||
|
||||
resolution_type:
|
||||
type: enum
|
||||
values:
|
||||
- code_fix
|
||||
- migration
|
||||
- config_change
|
||||
- test_fix
|
||||
- dependency_update
|
||||
- environment_setup
|
||||
- workflow_improvement
|
||||
- documentation_update
|
||||
- tooling_addition
|
||||
- seed_data_update
|
||||
description: "Type of fix applied"
|
||||
|
||||
severity:
|
||||
type: enum
|
||||
values:
|
||||
- critical
|
||||
- high
|
||||
- medium
|
||||
- low
|
||||
description: "Impact severity"
|
||||
|
||||
optional_fields:
|
||||
rails_version:
|
||||
type: string
|
||||
pattern: '^\d+\.\d+\.\d+$'
|
||||
description: "Rails version in X.Y.Z format"
|
||||
|
||||
related_components:
|
||||
type: array[string]
|
||||
description: "Other components involved"
|
||||
|
||||
tags:
|
||||
type: array[string]
|
||||
max_items: 8
|
||||
description: "Search keywords, lowercase and hyphen-separated"
|
||||
|
||||
validation_rules:
|
||||
- "All required fields must be present"
|
||||
- "Enum fields must match allowed values exactly"
|
||||
- "symptoms must be a YAML array with 1-5 items"
|
||||
- "date must match YYYY-MM-DD format"
|
||||
- "rails_version, if provided, must match X.Y.Z format"
|
||||
- "tags should be lowercase and hyphen-separated"
|
||||
@@ -0,0 +1,50 @@
|
||||
# YAML Frontmatter Schema
|
||||
|
||||
`schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce:compound`.
|
||||
|
||||
Use this file as the quick reference for:
|
||||
- required fields
|
||||
- enum values
|
||||
- validation expectations
|
||||
- category mapping
|
||||
|
||||
## Required Fields
|
||||
|
||||
- **module**: Module or area affected by the problem
|
||||
- **date**: ISO date in `YYYY-MM-DD`
|
||||
- **problem_type**: One of `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`, `developer_experience`, `workflow_issue`, `best_practice`, `documentation_gap`
|
||||
- **component**: One of `rails_model`, `rails_controller`, `rails_view`, `service_object`, `background_job`, `database`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `assistant`, `authentication`, `payments`, `development_workflow`, `testing_framework`, `documentation`, `tooling`
|
||||
- **symptoms**: YAML array with 1-5 concrete symptoms
|
||||
- **root_cause**: One of `missing_association`, `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`
|
||||
- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`, `seed_data_update`
|
||||
- **severity**: One of `critical`, `high`, `medium`, `low`
|
||||
|
||||
## Optional Fields
|
||||
|
||||
- **rails_version**: Rails version in `X.Y.Z` format
|
||||
- **related_components**: Other components involved
|
||||
- **tags**: Search keywords, lowercase and hyphen-separated
|
||||
|
||||
## Category Mapping
|
||||
|
||||
- `build_error` -> `docs/solutions/build-errors/`
|
||||
- `test_failure` -> `docs/solutions/test-failures/`
|
||||
- `runtime_error` -> `docs/solutions/runtime-errors/`
|
||||
- `performance_issue` -> `docs/solutions/performance-issues/`
|
||||
- `database_issue` -> `docs/solutions/database-issues/`
|
||||
- `security_issue` -> `docs/solutions/security-issues/`
|
||||
- `ui_bug` -> `docs/solutions/ui-bugs/`
|
||||
- `integration_issue` -> `docs/solutions/integration-issues/`
|
||||
- `logic_error` -> `docs/solutions/logic-errors/`
|
||||
- `developer_experience` -> `docs/solutions/developer-experience/`
|
||||
- `workflow_issue` -> `docs/solutions/workflow-issues/`
|
||||
- `best_practice` -> `docs/solutions/best-practices/`
|
||||
- `documentation_gap` -> `docs/solutions/documentation-gaps/`
|
||||
|
||||
## Validation Rules
|
||||
|
||||
1. All required fields must be present.
|
||||
2. Enum fields must match the allowed values exactly.
|
||||
3. `symptoms` must be a YAML array with 1-5 items.
|
||||
4. `date` must match `YYYY-MM-DD`.
|
||||
5. `rails_version`, if present, must match `X.Y.Z`.
|
||||
@@ -21,6 +21,16 @@ Captures problem solutions while context is fresh, creating structured documenta
|
||||
/ce:compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Support Files
|
||||
|
||||
These files are the durable contract for the workflow. Read them on-demand at the step that needs them — do not bulk-load at skill start.
|
||||
|
||||
- `references/schema.yaml` — canonical frontmatter fields and enum values (read when validating YAML)
|
||||
- `references/yaml-schema.md` — category mapping from problem_type to directory (read when classifying)
|
||||
- `assets/resolution-template.md` — section structure for new docs (read when assembling)
|
||||
|
||||
When spawning subagents, pass the relevant file contents into the task prompt so they have the contract without needing cross-skill paths.
|
||||
|
||||
## Execution Strategy
|
||||
|
||||
**Always run full mode by default.** Proceed directly to Phase 1 unless the user explicitly requests compact-safe mode (e.g., `/ce:compound --compact` or "use compact mode").
|
||||
@@ -68,36 +78,11 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence when identifying problem type, component, and symptoms
|
||||
- Validates all enum fields against the schema values below
|
||||
- Maps problem_type to the `docs/solutions/` category directory
|
||||
- Reads `references/schema.yaml` for enum validation
|
||||
- Reads `references/yaml-schema.md` for category mapping into `docs/solutions/`
|
||||
- Suggests a filename using the pattern `[sanitized-problem-slug]-[date].md`
|
||||
- Returns: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, and suggested filename
|
||||
|
||||
**Schema enum values (validate against these exactly):**
|
||||
|
||||
- **problem_type**: build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap
|
||||
- **component**: rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling
|
||||
- **root_cause**: missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup
|
||||
- **resolution_type**: code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update
|
||||
- **severity**: critical, high, medium, low
|
||||
|
||||
**Category mapping (problem_type -> directory):**
|
||||
|
||||
| problem_type | Directory |
|
||||
|---|---|
|
||||
| build_error | build-errors/ |
|
||||
| test_failure | test-failures/ |
|
||||
| runtime_error | runtime-errors/ |
|
||||
| performance_issue | performance-issues/ |
|
||||
| database_issue | database-issues/ |
|
||||
| security_issue | security-issues/ |
|
||||
| ui_bug | ui-bugs/ |
|
||||
| integration_issue | integration-issues/ |
|
||||
| logic_error | logic-errors/ |
|
||||
| developer_experience | developer-experience/ |
|
||||
| workflow_issue | workflow-issues/ |
|
||||
| best_practice | best-practices/ |
|
||||
| documentation_gap | documentation-gaps/ |
|
||||
- Does not invent enum values, categories, or frontmatter fields from memory; reads the schema and mapping files above
|
||||
|
||||
#### 2. **Solution Extractor**
|
||||
- Analyzes all investigation steps
|
||||
@@ -169,11 +154,13 @@ The orchestrating agent (main conversation) performs these steps:
|
||||
|
||||
When updating an existing doc, preserve its file path and frontmatter structure. Update the solution, code examples, prevention tips, and any stale references. Add a `last_updated: YYYY-MM-DD` field to the frontmatter. Do not change the title unless the problem framing has materially shifted.
|
||||
|
||||
3. Assemble complete markdown file from the collected pieces
|
||||
4. Validate YAML frontmatter against schema
|
||||
3. Assemble complete markdown file from the collected pieces, reading `assets/resolution-template.md` for the section structure of new docs
|
||||
4. Validate YAML frontmatter against `references/schema.yaml`
|
||||
5. Create directory if needed: `mkdir -p docs/solutions/[category]/`
|
||||
6. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md`
|
||||
|
||||
When creating a new doc, preserve the section order from `assets/resolution-template.md` unless the user explicitly asks for a different structure.
|
||||
|
||||
</sequential_tasks>
|
||||
|
||||
### Phase 2.5: Selective Refresh Check
|
||||
@@ -253,8 +240,8 @@ When context budget is tight, this mode skips parallel subagents entirely. The o
|
||||
The orchestrator (main conversation) performs ALL of the following in one sequential pass:
|
||||
|
||||
1. **Extract from conversation**: Identify the problem, root cause, and solution from conversation history. Also read MEMORY.md from the auto memory directory if it exists -- use any relevant notes as supplementary context alongside conversation history. Tag any memory-sourced content incorporated into the final doc with "(auto memory [claude])"
|
||||
2. **Classify**: Determine category and filename (same categories as full mode)
|
||||
3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` with:
|
||||
2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine category and filename from them
|
||||
3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using `assets/resolution-template.md` as the base structure, with:
|
||||
- YAML frontmatter (title, category, date, tags)
|
||||
- Problem description (1-2 sentences)
|
||||
- Root cause (1-2 sentences)
|
||||
@@ -400,9 +387,9 @@ Build → Test → Find Issue → Research → Improve → Document → Validate
|
||||
|
||||
<manual_override> Use /ce:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
||||
|
||||
## Routes To
|
||||
## Output
|
||||
|
||||
`compound-docs` skill
|
||||
Writes the final learning directly into `docs/solutions/`.
|
||||
|
||||
## Applicable Specialized Agents
|
||||
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: [Clear problem title]
|
||||
date: [YYYY-MM-DD]
|
||||
category: [docs/solutions subdirectory]
|
||||
module: [Module or area]
|
||||
problem_type: [schema enum]
|
||||
component: [schema enum]
|
||||
symptoms:
|
||||
- [Observable symptom 1]
|
||||
root_cause: [schema enum]
|
||||
resolution_type: [schema enum]
|
||||
severity: [schema enum]
|
||||
tags: [keyword-one, keyword-two]
|
||||
---
|
||||
|
||||
# [Clear problem title]
|
||||
|
||||
## Problem
|
||||
[1-2 sentence description of the issue and user-visible impact]
|
||||
|
||||
## Symptoms
|
||||
- [Observable symptom or error]
|
||||
|
||||
## What Didn't Work
|
||||
- [Attempted fix and why it failed]
|
||||
|
||||
## Solution
|
||||
[The fix that worked, including code snippets when useful]
|
||||
|
||||
## Why This Works
|
||||
[Root cause explanation and why the fix addresses it]
|
||||
|
||||
## Prevention
|
||||
- [Concrete practice, test, or guardrail]
|
||||
|
||||
## Related Issues
|
||||
- [Related docs or issues, if any]
|
||||
@@ -0,0 +1,127 @@
|
||||
# Documentation schema for learnings written by ce:compound
|
||||
# Treat this as the canonical frontmatter contract for docs/solutions/.
|
||||
|
||||
required_fields:
|
||||
module:
|
||||
type: string
|
||||
description: "Module or area affected by the problem"
|
||||
|
||||
date:
|
||||
type: string
|
||||
pattern: '^\d{4}-\d{2}-\d{2}$'
|
||||
description: "Date the problem was solved (YYYY-MM-DD)"
|
||||
|
||||
problem_type:
|
||||
type: enum
|
||||
values:
|
||||
- build_error
|
||||
- test_failure
|
||||
- runtime_error
|
||||
- performance_issue
|
||||
- database_issue
|
||||
- security_issue
|
||||
- ui_bug
|
||||
- integration_issue
|
||||
- logic_error
|
||||
- developer_experience
|
||||
- workflow_issue
|
||||
- best_practice
|
||||
- documentation_gap
|
||||
description: "Primary category of the problem"
|
||||
|
||||
component:
|
||||
type: enum
|
||||
values:
|
||||
- rails_model
|
||||
- rails_controller
|
||||
- rails_view
|
||||
- service_object
|
||||
- background_job
|
||||
- database
|
||||
- frontend_stimulus
|
||||
- hotwire_turbo
|
||||
- email_processing
|
||||
- brief_system
|
||||
- assistant
|
||||
- authentication
|
||||
- payments
|
||||
- development_workflow
|
||||
- testing_framework
|
||||
- documentation
|
||||
- tooling
|
||||
description: "Component involved"
|
||||
|
||||
symptoms:
|
||||
type: array[string]
|
||||
min_items: 1
|
||||
max_items: 5
|
||||
description: "Observable symptoms such as errors or broken behavior"
|
||||
|
||||
root_cause:
|
||||
type: enum
|
||||
values:
|
||||
- missing_association
|
||||
- missing_include
|
||||
- missing_index
|
||||
- wrong_api
|
||||
- scope_issue
|
||||
- thread_violation
|
||||
- async_timing
|
||||
- memory_leak
|
||||
- config_error
|
||||
- logic_error
|
||||
- test_isolation
|
||||
- missing_validation
|
||||
- missing_permission
|
||||
- missing_workflow_step
|
||||
- inadequate_documentation
|
||||
- missing_tooling
|
||||
- incomplete_setup
|
||||
description: "Fundamental technical cause of the problem"
|
||||
|
||||
resolution_type:
|
||||
type: enum
|
||||
values:
|
||||
- code_fix
|
||||
- migration
|
||||
- config_change
|
||||
- test_fix
|
||||
- dependency_update
|
||||
- environment_setup
|
||||
- workflow_improvement
|
||||
- documentation_update
|
||||
- tooling_addition
|
||||
- seed_data_update
|
||||
description: "Type of fix applied"
|
||||
|
||||
severity:
|
||||
type: enum
|
||||
values:
|
||||
- critical
|
||||
- high
|
||||
- medium
|
||||
- low
|
||||
description: "Impact severity"
|
||||
|
||||
optional_fields:
|
||||
rails_version:
|
||||
type: string
|
||||
pattern: '^\d+\.\d+\.\d+$'
|
||||
description: "Rails version in X.Y.Z format"
|
||||
|
||||
related_components:
|
||||
type: array[string]
|
||||
description: "Other components involved"
|
||||
|
||||
tags:
|
||||
type: array[string]
|
||||
max_items: 8
|
||||
description: "Search keywords, lowercase and hyphen-separated"
|
||||
|
||||
validation_rules:
|
||||
- "All required fields must be present"
|
||||
- "Enum fields must match allowed values exactly"
|
||||
- "symptoms must be a YAML array with 1-5 items"
|
||||
- "date must match YYYY-MM-DD format"
|
||||
- "rails_version, if provided, must match X.Y.Z format"
|
||||
- "tags should be lowercase and hyphen-separated"
|
||||
@@ -0,0 +1,50 @@
|
||||
# YAML Frontmatter Schema
|
||||
|
||||
`schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce:compound`.
|
||||
|
||||
Use this file as the quick reference for:
|
||||
- required fields
|
||||
- enum values
|
||||
- validation expectations
|
||||
- category mapping
|
||||
|
||||
## Required Fields
|
||||
|
||||
- **module**: Module or area affected by the problem
|
||||
- **date**: ISO date in `YYYY-MM-DD`
|
||||
- **problem_type**: One of `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`, `developer_experience`, `workflow_issue`, `best_practice`, `documentation_gap`
|
||||
- **component**: One of `rails_model`, `rails_controller`, `rails_view`, `service_object`, `background_job`, `database`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `assistant`, `authentication`, `payments`, `development_workflow`, `testing_framework`, `documentation`, `tooling`
|
||||
- **symptoms**: YAML array with 1-5 concrete symptoms
|
||||
- **root_cause**: One of `missing_association`, `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`
|
||||
- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`, `seed_data_update`
|
||||
- **severity**: One of `critical`, `high`, `medium`, `low`
|
||||
|
||||
## Optional Fields
|
||||
|
||||
- **rails_version**: Rails version in `X.Y.Z` format
|
||||
- **related_components**: Other components involved
|
||||
- **tags**: Search keywords, lowercase and hyphen-separated
|
||||
|
||||
## Category Mapping
|
||||
|
||||
- `build_error` -> `docs/solutions/build-errors/`
|
||||
- `test_failure` -> `docs/solutions/test-failures/`
|
||||
- `runtime_error` -> `docs/solutions/runtime-errors/`
|
||||
- `performance_issue` -> `docs/solutions/performance-issues/`
|
||||
- `database_issue` -> `docs/solutions/database-issues/`
|
||||
- `security_issue` -> `docs/solutions/security-issues/`
|
||||
- `ui_bug` -> `docs/solutions/ui-bugs/`
|
||||
- `integration_issue` -> `docs/solutions/integration-issues/`
|
||||
- `logic_error` -> `docs/solutions/logic-errors/`
|
||||
- `developer_experience` -> `docs/solutions/developer-experience/`
|
||||
- `workflow_issue` -> `docs/solutions/workflow-issues/`
|
||||
- `best_practice` -> `docs/solutions/best-practices/`
|
||||
- `documentation_gap` -> `docs/solutions/documentation-gaps/`
|
||||
|
||||
## Validation Rules
|
||||
|
||||
1. All required fields must be present.
|
||||
2. Enum fields must match the allowed values exactly.
|
||||
3. `symptoms` must be a YAML array with 1-5 items.
|
||||
4. `date` must match `YYYY-MM-DD`.
|
||||
5. `rails_version`, if present, must match `X.Y.Z`.
|
||||
@@ -1,511 +0,0 @@
|
||||
---
|
||||
name: compound-docs
|
||||
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
|
||||
disable-model-invocation: true
|
||||
allowed-tools:
|
||||
- Read # Parse conversation context
|
||||
- Write # Create resolution docs
|
||||
- Bash # Create directories
|
||||
- Grep # Search existing docs
|
||||
preconditions:
|
||||
- Problem has been solved (not in-progress)
|
||||
- Solution has been verified working
|
||||
---
|
||||
|
||||
# compound-docs Skill
|
||||
|
||||
**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).
|
||||
|
||||
## 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., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability.
|
||||
|
||||
---
|
||||
|
||||
<critical_sequence name="documentation-capture" enforce_order="strict">
|
||||
|
||||
## 7-Step 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:
|
||||
|
||||
**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
|
||||
|
||||
**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), 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 docs/solutions/ for similar issues:
|
||||
|
||||
```bash
|
||||
# Search by error message keywords
|
||||
grep -r "exact error phrase" docs/solutions/
|
||||
|
||||
# Search by symptom category
|
||||
ls docs/solutions/[category]/
|
||||
```
|
||||
|
||||
**IF similar issue found:**
|
||||
|
||||
THEN present decision options:
|
||||
|
||||
```
|
||||
Found similar issue: docs/solutions/[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`.
|
||||
|
||||
</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:**
|
||||
|
||||
```bash
|
||||
PROBLEM_TYPE="[from validated YAML]"
|
||||
CATEGORY="[mapped from problem_type]"
|
||||
FILENAME="[generated-filename].md"
|
||||
DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"
|
||||
|
||||
# Create directory if needed
|
||||
mkdir -p "docs/solutions/${CATEGORY}"
|
||||
|
||||
# Write documentation using template from assets/resolution-template.md
|
||||
# (Content populated with Step 2 context and validated YAML frontmatter)
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- Single file in category directory
|
||||
- Enum validation ensures consistent categorization
|
||||
|
||||
**Create documentation:** Populate the structure from `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-Reference & Critical Pattern Detection
|
||||
|
||||
If similar issues found in Step 3:
|
||||
|
||||
**Update existing doc:**
|
||||
|
||||
```bash
|
||||
# Add Related Issues link to similar doc
|
||||
echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]
|
||||
```
|
||||
|
||||
**Update new doc:**
|
||||
Already includes cross-reference from Step 6.
|
||||
|
||||
**Update patterns if applicable:**
|
||||
|
||||
If this represents a common pattern (3+ similar issues):
|
||||
|
||||
```bash
|
||||
# Add to docs/solutions/patterns/common-solutions.md
|
||||
cat >> docs/solutions/patterns/common-solutions.md << 'EOF'
|
||||
|
||||
## [Pattern Name]
|
||||
|
||||
**Common symptom:** [Description]
|
||||
**Root cause:** [Technical explanation]
|
||||
**Solution pattern:** [General approach]
|
||||
|
||||
**Examples:**
|
||||
- [Link to doc 1]
|
||||
- [Link to doc 2]
|
||||
- [Link to doc 3]
|
||||
EOF
|
||||
```
|
||||
|
||||
**Critical Pattern Detection (Optional Proactive Suggestion):**
|
||||
|
||||
If this issue has automatic indicators suggesting it might be critical:
|
||||
- Severity: `critical` in YAML
|
||||
- Affects multiple modules OR foundational stage (Stage 2 or 3)
|
||||
- Non-obvious solution
|
||||
|
||||
Then in the decision menu (Step 8), add a note:
|
||||
```
|
||||
💡 This might be worth adding to Required Reading (Option 2)
|
||||
```
|
||||
|
||||
But **NEVER auto-promote**. User decides via decision menu (Option 2).
|
||||
|
||||
**Template for critical pattern addition:**
|
||||
|
||||
When user selects Option 2 (Add to Required Reading), use the template from `assets/critical-pattern-template.md` to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/critical-patterns.md`.
|
||||
</step>
|
||||
|
||||
</critical_sequence>
|
||||
|
||||
---
|
||||
|
||||
<decision_gate name="post-documentation" wait_for_user="true">
|
||||
|
||||
## Decision Menu After Capture
|
||||
|
||||
After successful documentation, present options and WAIT for user response:
|
||||
|
||||
```
|
||||
✓ Solution documented
|
||||
|
||||
File created:
|
||||
- docs/solutions/[category]/[filename].md
|
||||
|
||||
What's next?
|
||||
1. Continue workflow (recommended)
|
||||
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
|
||||
3. Link related issues - Connect to similar problems
|
||||
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
|
||||
5. Create new skill - Extract into new learning skill
|
||||
6. View documentation - See what was captured
|
||||
7. Other
|
||||
```
|
||||
|
||||
**Handle responses:**
|
||||
|
||||
**Option 1: Continue workflow**
|
||||
|
||||
- Return to calling skill/workflow
|
||||
- Documentation is complete
|
||||
|
||||
**Option 2: Add to Required Reading** ⭐ PRIMARY PATH FOR CRITICAL PATTERNS
|
||||
|
||||
User selects this when:
|
||||
- System made this mistake multiple times across different modules
|
||||
- Solution is non-obvious but must be followed every time
|
||||
- Foundational requirement (Rails, Rails API, threading, etc.)
|
||||
|
||||
Action:
|
||||
1. Extract pattern from the documentation
|
||||
2. Format as ❌ WRONG vs ✅ CORRECT with code examples
|
||||
3. Add to `docs/solutions/patterns/critical-patterns.md`
|
||||
4. Add cross-reference back to this doc
|
||||
5. Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation."
|
||||
|
||||
**Option 3: Link related issues**
|
||||
|
||||
- Prompt: "Which doc to link? (provide filename or describe)"
|
||||
- Search docs/solutions/ for the doc
|
||||
- Add cross-reference to both docs
|
||||
- Confirm: "✓ Cross-reference added"
|
||||
|
||||
**Option 4: Add to existing skill**
|
||||
|
||||
User selects this when the documented solution relates to an existing learning skill:
|
||||
|
||||
Action:
|
||||
1. Prompt: "Which skill? (hotwire-native, etc.)"
|
||||
2. Determine which reference file to update (resources.md, patterns.md, or examples.md)
|
||||
3. Add link and brief description to appropriate section
|
||||
4. Confirm: "✓ Added to [skill-name] skill in [file]"
|
||||
|
||||
Example: For Hotwire Native Tailwind variants solution:
|
||||
- Add to `hotwire-native/references/resources.md` under "Project-Specific Resources"
|
||||
- Add to `hotwire-native/references/examples.md` with link to solution doc
|
||||
|
||||
**Option 5: Create new skill**
|
||||
|
||||
User selects this when the solution represents the start of a new learning domain:
|
||||
|
||||
Action:
|
||||
1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)"
|
||||
2. Run `python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name]`
|
||||
3. Create initial reference files with this solution as first example
|
||||
4. Confirm: "✓ Created new [skill-name] skill with this solution as first example"
|
||||
|
||||
**Option 6: View documentation**
|
||||
|
||||
- Display the created documentation
|
||||
- Present decision menu again
|
||||
|
||||
**Option 7: Other**
|
||||
|
||||
- Ask what they'd like to do
|
||||
|
||||
</decision_gate>
|
||||
|
||||
---
|
||||
|
||||
<integration_protocol>
|
||||
|
||||
## Integration Points
|
||||
|
||||
**Invoked by:**
|
||||
- /compound command (primary interface)
|
||||
- Manual invocation in conversation after solution confirmed
|
||||
- Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc.
|
||||
|
||||
**Invokes:**
|
||||
- None (terminal skill - does not delegate to other skills)
|
||||
|
||||
**Handoff expectations:**
|
||||
All context needed for documentation should be present in conversation history before invocation.
|
||||
|
||||
</integration_protocol>
|
||||
|
||||
---
|
||||
|
||||
<success_criteria>
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Documentation is successful when ALL of the following are true:
|
||||
|
||||
- ✅ YAML frontmatter validated (all required fields, correct formats)
|
||||
- ✅ File created in docs/solutions/[category]/[filename].md
|
||||
- ✅ Enum values match schema.yaml exactly
|
||||
- ✅ Code examples included in solution section
|
||||
- ✅ Cross-references added if related issues found
|
||||
- ✅ User presented with decision menu and action confirmed
|
||||
|
||||
</success_criteria>
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Missing context:**
|
||||
|
||||
- Ask user for missing details
|
||||
- Don't proceed until critical info provided
|
||||
|
||||
**YAML validation failure:**
|
||||
|
||||
- Show specific errors
|
||||
- Present retry with corrected values
|
||||
- BLOCK until valid
|
||||
|
||||
**Similar issue ambiguity:**
|
||||
|
||||
- Present multiple matches
|
||||
- Let user choose: new doc, update existing, or link as duplicate
|
||||
|
||||
**Module not in modules documentation:**
|
||||
|
||||
- Warn but don't block
|
||||
- Proceed with documentation
|
||||
- Suggest: "Add [Module] to modules documentation if not there"
|
||||
|
||||
---
|
||||
|
||||
## Execution Guidelines
|
||||
|
||||
**MUST do:**
|
||||
- Validate YAML frontmatter (BLOCK if invalid per Step 5 validation gate)
|
||||
- Extract exact error messages from conversation
|
||||
- Include code examples in solution section
|
||||
- Create directories before writing files (`mkdir -p`)
|
||||
- Ask user and WAIT if critical context missing
|
||||
|
||||
**MUST NOT do:**
|
||||
- Skip YAML validation (validation gate is blocking)
|
||||
- Use vague descriptions (not searchable)
|
||||
- Omit code examples or cross-references
|
||||
|
||||
---
|
||||
|
||||
## Quality Guidelines
|
||||
|
||||
**Good documentation has:**
|
||||
|
||||
- ✅ Exact error messages (copy-paste from output)
|
||||
- ✅ Specific file:line references
|
||||
- ✅ Observable symptoms (what you saw, not interpretations)
|
||||
- ✅ Failed attempts documented (helps avoid wrong paths)
|
||||
- ✅ Technical explanation (not just "what" but "why")
|
||||
- ✅ Code examples (before/after if applicable)
|
||||
- ✅ Prevention guidance (how to catch early)
|
||||
- ✅ Cross-references (related issues)
|
||||
|
||||
**Avoid:**
|
||||
|
||||
- ❌ Vague descriptions ("something was wrong")
|
||||
- ❌ Missing technical details ("fixed the code")
|
||||
- ❌ No context (which version? which file?)
|
||||
- ❌ Just code dumps (explain why it works)
|
||||
- ❌ No prevention guidance
|
||||
- ❌ No cross-references
|
||||
|
||||
---
|
||||
|
||||
## Example Scenario
|
||||
|
||||
**User:** "That worked! The N+1 query is fixed."
|
||||
|
||||
**Skill activates:**
|
||||
|
||||
1. **Detect confirmation:** "That worked!" triggers auto-invoke
|
||||
2. **Gather context:**
|
||||
- Module: Brief System
|
||||
- Symptom: Brief generation taking >5 seconds, N+1 query when loading email threads
|
||||
- Failed attempts: Added pagination (didn't help), checked background job performance
|
||||
- Solution: Added eager loading with `includes(:emails)` on Brief model
|
||||
- Root cause: Missing eager loading causing separate database query per email thread
|
||||
3. **Check existing:** No similar issue found
|
||||
4. **Generate filename:** `n-plus-one-brief-generation-BriefSystem-20251110.md`
|
||||
5. **Validate YAML:**
|
||||
```yaml
|
||||
module: Brief System
|
||||
date: 2025-11-10
|
||||
problem_type: performance_issue
|
||||
component: rails_model
|
||||
symptoms:
|
||||
- "N+1 query when loading email threads"
|
||||
- "Brief generation taking >5 seconds"
|
||||
root_cause: missing_include
|
||||
severity: high
|
||||
tags: [n-plus-one, eager-loading, performance]
|
||||
```
|
||||
✅ Valid
|
||||
6. **Create documentation:**
|
||||
- `docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md`
|
||||
7. **Cross-reference:** None needed (no similar issues)
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
✓ Solution documented
|
||||
|
||||
File created:
|
||||
- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md
|
||||
|
||||
What's next?
|
||||
1. Continue workflow (recommended)
|
||||
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
|
||||
3. Link related issues - Connect to similar problems
|
||||
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
|
||||
5. Create new skill - Extract into new learning skill
|
||||
6. View documentation - See what was captured
|
||||
7. Other
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
**Not in Phase 7 scope, but potential:**
|
||||
|
||||
- Search by date range
|
||||
- Filter by severity
|
||||
- Tag-based search interface
|
||||
- Metrics (most common issues, resolution time)
|
||||
- Export to shareable format (community knowledge sharing)
|
||||
- Import community solutions
|
||||
@@ -1,34 +0,0 @@
|
||||
# Critical Pattern Template
|
||||
|
||||
Use this template when adding a pattern to `docs/solutions/patterns/critical-patterns.md`:
|
||||
|
||||
---
|
||||
|
||||
## N. [Pattern Name] (ALWAYS REQUIRED)
|
||||
|
||||
### ❌ WRONG ([Will cause X error])
|
||||
```[language]
|
||||
[code showing wrong approach]
|
||||
```
|
||||
|
||||
### ✅ CORRECT
|
||||
```[language]
|
||||
[code showing correct approach]
|
||||
```
|
||||
|
||||
**Why:** [Technical explanation of why this is required]
|
||||
|
||||
**Placement/Context:** [When this applies]
|
||||
|
||||
**Documented in:** `docs/solutions/[category]/[filename].md`
|
||||
|
||||
---
|
||||
|
||||
**Instructions:**
|
||||
1. Replace N with the next pattern number
|
||||
2. Replace [Pattern Name] with descriptive title
|
||||
3. Fill in WRONG example with code that causes the problem
|
||||
4. Fill in CORRECT example with the solution
|
||||
5. Explain the technical reason in "Why"
|
||||
6. Clarify when this pattern applies in "Placement/Context"
|
||||
7. Link to the full troubleshooting doc where this was originally solved
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
module: [Module name or "System" for system-wide]
|
||||
date: [YYYY-MM-DD]
|
||||
problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
|
||||
component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
|
||||
symptoms:
|
||||
- [Observable symptom 1 - specific error message or behavior]
|
||||
- [Observable symptom 2 - what user actually saw/experienced]
|
||||
root_cause: [missing_association|missing_include|missing_index|wrong_api|scope_issue|thread_violation|async_timing|memory_leak|config_error|logic_error|test_isolation|missing_validation|missing_permission]
|
||||
rails_version: [7.1.2 - optional]
|
||||
resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
|
||||
severity: [critical|high|medium|low]
|
||||
tags: [keyword1, keyword2, keyword3]
|
||||
---
|
||||
|
||||
# Troubleshooting: [Clear Problem Title]
|
||||
|
||||
## Problem
|
||||
[1-2 sentence clear description of the issue and what the user experienced]
|
||||
|
||||
## Environment
|
||||
- Module: [Name or "System-wide"]
|
||||
- Rails Version: [e.g., 7.1.2]
|
||||
- Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication controller"]
|
||||
- Date: [YYYY-MM-DD when this was solved]
|
||||
|
||||
## Symptoms
|
||||
- [Observable symptom 1 - what the user saw/experienced]
|
||||
- [Observable symptom 2 - error messages, visual issues, unexpected behavior]
|
||||
- [Continue as needed - be specific]
|
||||
|
||||
## What Didn't Work
|
||||
|
||||
**Attempted Solution 1:** [Description of what was tried]
|
||||
- **Why it failed:** [Technical reason this didn't solve the problem]
|
||||
|
||||
**Attempted Solution 2:** [Description of second attempt]
|
||||
- **Why it failed:** [Technical reason]
|
||||
|
||||
[Continue for all significant attempts that DIDN'T work]
|
||||
|
||||
[If nothing else was attempted first, write:]
|
||||
**Direct solution:** The problem was identified and fixed on the first attempt.
|
||||
|
||||
## Solution
|
||||
|
||||
[The actual fix that worked - provide specific details]
|
||||
|
||||
**Code changes** (if applicable):
|
||||
```ruby
|
||||
# Before (broken):
|
||||
[Show the problematic code]
|
||||
|
||||
# After (fixed):
|
||||
[Show the corrected code with explanation]
|
||||
```
|
||||
|
||||
**Database migration** (if applicable):
|
||||
```ruby
|
||||
# Migration change:
|
||||
[Show what was changed in the migration]
|
||||
```
|
||||
|
||||
**Commands run** (if applicable):
|
||||
```bash
|
||||
# Steps taken to fix:
|
||||
[Commands or actions]
|
||||
```
|
||||
|
||||
## Why This Works
|
||||
|
||||
[Technical explanation of:]
|
||||
1. What was the ROOT CAUSE of the problem?
|
||||
2. Why does the solution address this root cause?
|
||||
3. What was the underlying issue (API misuse, configuration error, Rails version issue, etc.)?
|
||||
|
||||
[Be detailed enough that future developers understand the "why", not just the "what"]
|
||||
|
||||
## Prevention
|
||||
|
||||
[How to avoid this problem in future development:]
|
||||
- [Specific coding practice, check, or pattern to follow]
|
||||
- [What to watch out for]
|
||||
- [How to catch this early]
|
||||
|
||||
## Related Issues
|
||||
|
||||
[If any similar problems exist in docs/solutions/, link to them:]
|
||||
- See also: [another-related-issue.md](../category/another-related-issue.md)
|
||||
- Similar to: [related-problem.md](../category/related-problem.md)
|
||||
|
||||
[If no related issues, write:]
|
||||
No related issues documented yet.
|
||||
@@ -1,65 +0,0 @@
|
||||
# YAML Frontmatter Schema
|
||||
|
||||
**See `.claude/skills/codify-docs/schema.yaml` for the complete schema specification.**
|
||||
|
||||
## Required Fields
|
||||
|
||||
- **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
|
||||
- **date** (string): ISO 8601 date (YYYY-MM-DD)
|
||||
- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
|
||||
- **component** (enum): One of [rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling]
|
||||
- **symptoms** (array): 1-5 specific observable symptoms
|
||||
- **root_cause** (enum): One of [missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup]
|
||||
- **resolution_type** (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
|
||||
- **severity** (enum): One of [critical, high, medium, low]
|
||||
|
||||
## Optional Fields
|
||||
|
||||
- **rails_version** (string): Rails version in X.Y.Z format
|
||||
- **tags** (array): Searchable keywords (lowercase, hyphen-separated)
|
||||
|
||||
## Validation Rules
|
||||
|
||||
1. All required fields must be present
|
||||
2. Enum fields must match allowed values exactly (case-sensitive)
|
||||
3. symptoms must be YAML array with 1-5 items
|
||||
4. date must match YYYY-MM-DD format
|
||||
5. rails_version (if provided) must match X.Y.Z format
|
||||
6. tags should be lowercase, hyphen-separated
|
||||
|
||||
## Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
module: Email Processing
|
||||
date: 2025-11-12
|
||||
problem_type: performance_issue
|
||||
component: rails_model
|
||||
symptoms:
|
||||
- "N+1 query when loading email threads"
|
||||
- "Brief generation taking >5 seconds"
|
||||
root_cause: missing_include
|
||||
rails_version: 7.1.2
|
||||
resolution_type: code_fix
|
||||
severity: high
|
||||
tags: [n-plus-one, eager-loading, performance]
|
||||
---
|
||||
```
|
||||
|
||||
## Category Mapping
|
||||
|
||||
Based on `problem_type`, documentation is filed in:
|
||||
|
||||
- **build_error** → `docs/solutions/build-errors/`
|
||||
- **test_failure** → `docs/solutions/test-failures/`
|
||||
- **runtime_error** → `docs/solutions/runtime-errors/`
|
||||
- **performance_issue** → `docs/solutions/performance-issues/`
|
||||
- **database_issue** → `docs/solutions/database-issues/`
|
||||
- **security_issue** → `docs/solutions/security-issues/`
|
||||
- **ui_bug** → `docs/solutions/ui-bugs/`
|
||||
- **integration_issue** → `docs/solutions/integration-issues/`
|
||||
- **logic_error** → `docs/solutions/logic-errors/`
|
||||
- **developer_experience** → `docs/solutions/developer-experience/`
|
||||
- **workflow_issue** → `docs/solutions/workflow-issues/`
|
||||
- **best_practice** → `docs/solutions/best-practices/`
|
||||
- **documentation_gap** → `docs/solutions/documentation-gaps/`
|
||||
@@ -1,176 +0,0 @@
|
||||
# CORA Documentation Schema
|
||||
# This schema MUST be validated before writing any documentation file
|
||||
|
||||
required_fields:
|
||||
module:
|
||||
type: string
|
||||
description: "Module/area of CORA (e.g., 'Email Processing', 'Brief System', 'Authentication')"
|
||||
examples:
|
||||
- "Email Processing"
|
||||
- "Brief System"
|
||||
- "Assistant"
|
||||
- "Authentication"
|
||||
|
||||
date:
|
||||
type: string
|
||||
pattern: '^\d{4}-\d{2}-\d{2}$'
|
||||
description: "Date when this problem was solved (YYYY-MM-DD)"
|
||||
|
||||
problem_type:
|
||||
type: enum
|
||||
values:
|
||||
- build_error # Rails, bundle, compilation errors
|
||||
- test_failure # Test failures, flaky tests
|
||||
- runtime_error # Exceptions, crashes during execution
|
||||
- performance_issue # Slow queries, memory issues, N+1 queries
|
||||
- database_issue # Migration, query, schema problems
|
||||
- security_issue # Authentication, authorization, XSS, SQL injection
|
||||
- ui_bug # Frontend, Stimulus, Turbo issues
|
||||
- integration_issue # External service, API integration problems
|
||||
- logic_error # Business logic bugs
|
||||
- developer_experience # DX issues: workflow, tooling, seed data, dev setup
|
||||
- workflow_issue # Development process, missing steps, unclear practices
|
||||
- best_practice # Documenting patterns and practices to follow
|
||||
- documentation_gap # Missing or inadequate documentation
|
||||
description: "Primary category of the problem"
|
||||
|
||||
component:
|
||||
type: enum
|
||||
values:
|
||||
- rails_model # ActiveRecord models
|
||||
- rails_controller # ActionController
|
||||
- rails_view # ERB templates, ViewComponent
|
||||
- service_object # Custom service classes
|
||||
- background_job # Sidekiq, Active Job
|
||||
- database # PostgreSQL, migrations, schema
|
||||
- frontend_stimulus # Stimulus JS controllers
|
||||
- hotwire_turbo # Turbo Streams, Turbo Drive
|
||||
- email_processing # Email handling, mailers
|
||||
- brief_system # Brief generation, summarization
|
||||
- assistant # AI assistant, prompts
|
||||
- authentication # Devise, user auth
|
||||
- payments # Stripe, billing
|
||||
- development_workflow # Dev process, seed data, tooling
|
||||
- testing_framework # Test setup, fixtures, VCR
|
||||
- documentation # README, guides, inline docs
|
||||
- tooling # Scripts, generators, CLI tools
|
||||
description: "CORA component involved"
|
||||
|
||||
symptoms:
|
||||
type: array[string]
|
||||
min_items: 1
|
||||
max_items: 5
|
||||
description: "Observable symptoms (error messages, visual issues, crashes)"
|
||||
examples:
|
||||
- "N+1 query detected in brief generation"
|
||||
- "Brief emails not appearing in summary"
|
||||
- "Turbo Stream response returns 404"
|
||||
|
||||
root_cause:
|
||||
type: enum
|
||||
values:
|
||||
- missing_association # Incorrect Rails associations
|
||||
- missing_include # Missing eager loading (N+1)
|
||||
- missing_index # Database performance issue
|
||||
- wrong_api # Using deprecated/incorrect Rails API
|
||||
- scope_issue # Incorrect query scope or filtering
|
||||
- thread_violation # Real-time unsafe operation
|
||||
- async_timing # Async/background job timing
|
||||
- memory_leak # Memory leak or excessive allocation
|
||||
- config_error # Configuration or environment issue
|
||||
- logic_error # Algorithm/business logic bug
|
||||
- test_isolation # Test isolation or fixture issue
|
||||
- missing_validation # Missing model validation
|
||||
- missing_permission # Authorization check missing
|
||||
- missing_workflow_step # Skipped or undocumented workflow step
|
||||
- inadequate_documentation # Missing or unclear documentation
|
||||
- missing_tooling # Lacking helper scripts or automation
|
||||
- incomplete_setup # Missing seed data, fixtures, or config
|
||||
description: "Fundamental cause of the problem"
|
||||
|
||||
resolution_type:
|
||||
type: enum
|
||||
values:
|
||||
- code_fix # Fixed by changing source code
|
||||
- migration # Fixed by database migration
|
||||
- config_change # Fixed by changing configuration
|
||||
- test_fix # Fixed by correcting tests
|
||||
- dependency_update # Fixed by updating gem/dependency
|
||||
- environment_setup # Fixed by environment configuration
|
||||
- workflow_improvement # Improved development workflow or process
|
||||
- documentation_update # Added or updated documentation
|
||||
- tooling_addition # Added helper script or automation
|
||||
- seed_data_update # Updated db/seeds.rb or fixtures
|
||||
description: "Type of fix applied"
|
||||
|
||||
severity:
|
||||
type: enum
|
||||
values:
|
||||
- critical # Blocks production or development (build fails, data loss)
|
||||
- high # Impairs core functionality (feature broken, security issue)
|
||||
- medium # Affects specific feature (UI broken, performance impact)
|
||||
- low # Minor issue or edge case
|
||||
description: "Impact severity"
|
||||
|
||||
optional_fields:
|
||||
rails_version:
|
||||
type: string
|
||||
pattern: '^\d+\.\d+\.\d+$'
|
||||
description: "Rails version where this was encountered (e.g., '7.1.0')"
|
||||
|
||||
related_components:
|
||||
type: array[string]
|
||||
description: "Other components that interact with this issue"
|
||||
|
||||
tags:
|
||||
type: array[string]
|
||||
max_items: 8
|
||||
description: "Searchable keywords (lowercase, hyphen-separated)"
|
||||
examples:
|
||||
- "n-plus-one"
|
||||
- "eager-loading"
|
||||
- "test-isolation"
|
||||
- "turbo-stream"
|
||||
|
||||
validation_rules:
|
||||
- "module must be a valid CORA module name"
|
||||
- "date must be in YYYY-MM-DD format"
|
||||
- "problem_type must match one of the enum values"
|
||||
- "component must match one of the enum values"
|
||||
- "symptoms must be specific and observable (not vague)"
|
||||
- "root_cause must be the ACTUAL cause, not a symptom"
|
||||
- "resolution_type must match one of the enum values"
|
||||
- "severity must match one of the enum values"
|
||||
- "tags should be lowercase, hyphen-separated"
|
||||
|
||||
# Example valid front matter:
|
||||
# ---
|
||||
# module: Email Processing
|
||||
# date: 2025-11-12
|
||||
# problem_type: performance_issue
|
||||
# component: rails_model
|
||||
# symptoms:
|
||||
# - N+1 query when loading email threads
|
||||
# - Brief generation taking >5 seconds
|
||||
# root_cause: missing_include
|
||||
# rails_version: 7.1.2
|
||||
# resolution_type: code_fix
|
||||
# severity: high
|
||||
# tags: [n-plus-one, eager-loading, performance]
|
||||
# ---
|
||||
#
|
||||
# Example DX issue front matter:
|
||||
# ---
|
||||
# module: Development Workflow
|
||||
# date: 2025-11-13
|
||||
# problem_type: developer_experience
|
||||
# component: development_workflow
|
||||
# symptoms:
|
||||
# - No example data for new feature in development
|
||||
# - Rails db:seed doesn't demonstrate new capabilities
|
||||
# root_cause: incomplete_setup
|
||||
# rails_version: 7.1.2
|
||||
# resolution_type: seed_data_update
|
||||
# severity: low
|
||||
# tags: [seed-data, dx, workflow]
|
||||
# ---
|
||||
Reference in New Issue
Block a user