john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ce-compound): add track-based schema for bug vs knowledge learnings (#445)

Browse Source 
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Trevin Chow
2026-03-29 14:21:13 -07:00
committed by GitHub
parent 44e3e77dc0
commit 739109c03c
7 changed files with 529 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md
View File

@@ -1,3 +1,14 @@
# Resolution Templates
Choose the template matching the problem_type track (see `references/schema.yaml`).
---
## Bug Track Template
Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
```markdown
--- ---
title: [Clear problem title] title: [Clear problem title]
date: [YYYY-MM-DD] date: [YYYY-MM-DD]
@@ -35,3 +46,45 @@ tags: [keyword-one, keyword-two]
## Related Issues ## Related Issues
- [Related docs or issues, if any] - [Related docs or issues, if any]
```
---
## Knowledge Track Template
Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
```markdown
---
title: [Clear, descriptive title]
date: [YYYY-MM-DD]
category: [docs/solutions subdirectory]
module: [Module or area]
problem_type: [schema enum]
component: [schema enum]
severity: [schema enum]
applies_when:
- [Condition where this applies]
tags: [keyword-one, keyword-two]
---
# [Clear, descriptive title]
## Context
[What situation, gap, or friction prompted this guidance]
## Guidance
[The practice, pattern, or recommendation with code examples when useful]
## Why This Matters
[Rationale and impact of following or not following this guidance]
## When to Apply
- [Conditions or situations where this applies]
## Examples
[Concrete before/after or usage examples showing the practice in action]
## Related
- [Related docs or issues, if any]
```

203
plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml
View File

@@ -1,15 +1,45 @@
# Documentation schema for learnings written by ce:compound # Documentation schema for learnings written by ce:compound
# Treat this as the canonical frontmatter contract for docs/solutions/. # Treat this as the canonical frontmatter contract for docs/solutions/.
#
# The schema has two tracks based on problem_type:
# Bug track — problem_type is a defect or failure (build_error, test_failure, etc.)
# Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
#
# Both tracks share the same required core fields. The tracks differ in which
# additional fields are required vs optional (see track_rules below).
# --- Track classification ---------------------------------------------------
tracks:
bug:
description: "Defects, failures, and errors that were diagnosed and fixed"
problem_types:
- build_error
- test_failure
- runtime_error
- performance_issue
- database_issue
- security_issue
- ui_bug
- integration_issue
- logic_error
knowledge:
description: "Best practices, workflow improvements, patterns, and documentation"
problem_types:
- best_practice
- documentation_gap
- workflow_issue
- developer_experience
# --- Fields required by BOTH tracks -----------------------------------------
required_fields: required_fields:
module: module:
type: string type: string
description: "Module or area affected by the problem" description: "Module or area affected"
date: date:
type: string type: string
pattern: '^\d{4}-\d{2}-\d{2}$' pattern: '^\d{4}-\d{2}-\d{2}$'
description: "Date the problem was solved (YYYY-MM-DD)" description: "Date documented (YYYY-MM-DD)"
problem_type: problem_type:
type: enum type: enum
@@ -27,7 +57,7 @@ required_fields:
- workflow_issue - workflow_issue
- best_practice - best_practice
- documentation_gap - documentation_gap
description: "Primary category of the problem" description: "Primary category — determines track (bug vs knowledge)"
component: component:
type: enum type: enum
@@ -51,49 +81,6 @@ required_fields:
- tooling - tooling
description: "Component involved" 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: severity:
type: enum type: enum
values: values:
@@ -103,12 +90,99 @@ required_fields:
- low - low
description: "Impact severity" description: "Impact severity"
optional_fields: # --- Track-specific rules ----------------------------------------------------
rails_version: track_rules:
type: string bug:
pattern: '^\d+\.\d+\.\d+$' required:
description: "Rails version in X.Y.Z format" 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"
knowledge:
optional:
applies_when:
type: array[string]
max_items: 5
description: "Conditions or situations where this guidance applies"
symptoms:
type: array[string]
max_items: 5
description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
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: "Underlying cause, if there is a specific one (optional for knowledge track)"
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 change, if applicable (optional for knowledge track)"
# --- Fields optional for BOTH tracks ----------------------------------------
optional_fields:
related_components: related_components:
type: array[string] type: array[string]
description: "Other components involved" description: "Other components involved"
@@ -118,10 +192,31 @@ optional_fields:
max_items: 8 max_items: 8
description: "Search keywords, lowercase and hyphen-separated" description: "Search keywords, lowercase and hyphen-separated"
# --- Fields optional for bug track only -------------------------------------
bug_optional_fields:
rails_version:
type: string
pattern: '^\d+\.\d+\.\d+$'
description: "Rails version in X.Y.Z format. Only relevant for bug-track docs."
# --- Backward compatibility --------------------------------------------------
# Docs created before the track system was introduced may have bug-track
# fields (symptoms, root_cause, resolution_type) on knowledge-type
# problem_types. These are valid legacy docs:
# - Bug-track fields present on a knowledge-track doc are harmless. Do not
# strip them during refresh unless the doc is being rewritten for other reasons.
# - When creating NEW docs, follow the track rules above.
# --- Validation rules --------------------------------------------------------
validation_rules: validation_rules:
- "All required fields must be present" - "Determine track from problem_type using the tracks section above"
- "All shared required_fields must be present"
- "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
- "Knowledge-track docs have no additional required fields beyond the shared ones"
- "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
- "Track-specific optional fields may be included but are not required"
- "Enum fields must match allowed values exactly" - "Enum fields must match allowed values exactly"
- "symptoms must be a YAML array with 1-5 items" - "Array fields must respect min_items/max_items when specified"
- "date must match YYYY-MM-DD format" - "date must match YYYY-MM-DD format"
- "rails_version, if provided, must match X.Y.Z format" - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
- "tags should be lowercase and hyphen-separated" - "tags should be lowercase and hyphen-separated"

63
plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md
View File

@@ -7,24 +7,57 @@ Use this file as the quick reference for:
- enum values - enum values
- validation expectations - validation expectations
- category mapping - category mapping
- track classification (bug vs knowledge)
## Required Fields ## Tracks
- **module**: Module or area affected by the problem The `problem_type` determines which **track** applies. Each track has different required and optional fields.
| Track | problem_types | Description |
|-------|--------------|-------------|
| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
## Required Fields (both tracks)
- **module**: Module or area affected
- **date**: ISO date in `YYYY-MM-DD` - **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` - **problem_type**: One of the values listed in the Tracks table above
- **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` - **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` - **severity**: One of `critical`, `high`, `medium`, `low`
## Optional Fields ## Bug Track Fields
Required:
- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
- **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`
## Knowledge Track Fields
No additional required fields beyond the shared ones. All fields below are optional:
- **applies_when**: Conditions or situations where this guidance applies
- **symptoms**: Observable gaps or friction that prompted this guidance
- **root_cause**: Underlying cause, if there is a specific one
- **resolution_type**: Type of change, if applicable
## Optional Fields (both tracks)
- **rails_version**: Rails version in `X.Y.Z` format
- **related_components**: Other components involved - **related_components**: Other components involved
- **tags**: Search keywords, lowercase and hyphen-separated - **tags**: Search keywords, lowercase and hyphen-separated
## Optional Fields (bug track only)
- **rails_version**: Rails version in `X.Y.Z` format
## Backward Compatibility
Docs created before the track system may have `symptoms`/`root_cause`/`resolution_type` on knowledge-type problem_types. These are valid legacy docs:
- Bug-track fields present on a knowledge-track doc are harmless. Do not strip them during refresh unless the doc is being rewritten for other reasons.
- When creating **new** docs, follow the track rules above.
## Category Mapping ## Category Mapping
- `build_error` -> `docs/solutions/build-errors/` - `build_error` -> `docs/solutions/build-errors/`
@@ -43,8 +76,12 @@ Use this file as the quick reference for:
## Validation Rules ## Validation Rules
1. All required fields must be present. 1. Determine the track from `problem_type` using the Tracks table.
2. Enum fields must match the allowed values exactly. 2. All shared required fields must be present.
3. `symptoms` must be a YAML array with 1-5 items. 3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
4. `date` must match `YYYY-MM-DD`. 4. Knowledge-track docs have no additional required fields beyond the shared ones.
5. `rails_version`, if present, must match `X.Y.Z`. 5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
6. Enum fields must match the allowed values exactly.
7. Array fields must respect min/max item counts.
8. `date` must match `YYYY-MM-DD`.
9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.

44
plugins/compound-engineering/skills/ce-compound/SKILL.md
View File

@@ -75,24 +75,24 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
#### 1. **Context Analyzer** #### 1. **Context Analyzer**
- Extracts conversation history - Extracts conversation history
- Identifies problem type, component, symptoms - Reads `references/schema.yaml` for enum validation and **track classification**
- Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence when identifying problem type, component, and symptoms - Determines the track (bug or knowledge) from the problem_type
- Reads `references/schema.yaml` for enum validation - Identifies problem type, component, and track-appropriate fields:
- **Bug track**: symptoms, root_cause, resolution_type
- **Knowledge track**: applies_when (symptoms/root_cause/resolution_type optional)
- Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence
- Reads `references/yaml-schema.md` for category mapping into `docs/solutions/` - Reads `references/yaml-schema.md` for category mapping into `docs/solutions/`
- Suggests a filename using the pattern `[sanitized-problem-slug]-[date].md` - 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 - Returns: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, suggested filename, and which track applies
- Does not invent enum values, categories, or frontmatter fields from memory; reads the schema and mapping files above - Does not invent enum values, categories, or frontmatter fields from memory; reads the schema and mapping files above
- Does not force bug-track fields onto knowledge-track learnings or vice versa
#### 2. **Solution Extractor** #### 2. **Solution Extractor**
- Analyzes all investigation steps - Reads `references/schema.yaml` for track classification (bug vs knowledge)
- Identifies root cause - Adapts output structure based on the problem_type track
- Extracts working solution with code examples
- Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence -- conversation history and the verified fix take priority; if memory notes contradict the conversation, note the contradiction as cautionary context - Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence -- conversation history and the verified fix take priority; if memory notes contradict the conversation, note the contradiction as cautionary context
- Develops prevention strategies and best practices guidance
- Generates test cases if applicable
- Returns: Solution content block including prevention section
**Expected output sections (follow this structure):** **Bug track output sections:**
- **Problem**: 1-2 sentence description of the issue - **Problem**: 1-2 sentence description of the issue
- **Symptoms**: Observable symptoms (error messages, behavior) - **Symptoms**: Observable symptoms (error messages, behavior)
@@ -101,6 +101,14 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
- **Why This Works**: Root cause explanation and why the solution addresses it - **Why This Works**: Root cause explanation and why the solution addresses it
- **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., gem configurations, test assertions, linting rules) - **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., gem configurations, test assertions, linting rules)
**Knowledge track output sections:**
- **Context**: What situation, gap, or friction prompted this guidance
- **Guidance**: The practice, pattern, or recommendation with code examples when useful
- **Why This Matters**: Rationale and impact of following or not following this guidance
- **When to Apply**: Conditions or situations where this applies
- **Examples**: Concrete before/after or usage examples showing the practice in action
#### 3. **Related Docs Finder** #### 3. **Related Docs Finder**
- Searches `docs/solutions/` for related documentation - Searches `docs/solutions/` for related documentation
- Identifies cross-references and links - Identifies cross-references and links
@@ -238,14 +246,12 @@ 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: 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])" 1. **Extract from conversation**: Identify the problem 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**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine category and filename from them 2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine track (bug vs knowledge), category, and filename
3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using `assets/resolution-template.md` as the base structure, with: 3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with:
- YAML frontmatter (title, category, date, tags) - YAML frontmatter with track-appropriate fields
- Problem description (1-2 sentences) - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
- Root cause (1-2 sentences) - Knowledge track: Context, guidance with key examples, one applicability note
- Solution with key code snippets
- One prevention tip
4. **Skip specialized agent reviews** (Phase 3) to conserve context 4. **Skip specialized agent reviews** (Phase 3) to conserve context
**Compact-safe output:** **Compact-safe output:**

53
plugins/compound-engineering/skills/ce-compound/assets/resolution-template.md
View File

@@ -1,3 +1,14 @@
# Resolution Templates
Choose the template matching the problem_type track (see `references/schema.yaml`).
---
## Bug Track Template
Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
```markdown
--- ---
title: [Clear problem title] title: [Clear problem title]
date: [YYYY-MM-DD] date: [YYYY-MM-DD]
@@ -35,3 +46,45 @@ tags: [keyword-one, keyword-two]
## Related Issues ## Related Issues
- [Related docs or issues, if any] - [Related docs or issues, if any]
```
---
## Knowledge Track Template
Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
```markdown
---
title: [Clear, descriptive title]
date: [YYYY-MM-DD]
category: [docs/solutions subdirectory]
module: [Module or area]
problem_type: [schema enum]
component: [schema enum]
severity: [schema enum]
applies_when:
- [Condition where this applies]
tags: [keyword-one, keyword-two]
---
# [Clear, descriptive title]
## Context
[What situation, gap, or friction prompted this guidance]
## Guidance
[The practice, pattern, or recommendation with code examples when useful]
## Why This Matters
[Rationale and impact of following or not following this guidance]
## When to Apply
- [Conditions or situations where this applies]
## Examples
[Concrete before/after or usage examples showing the practice in action]
## Related
- [Related docs or issues, if any]
```

203
plugins/compound-engineering/skills/ce-compound/references/schema.yaml
View File

@@ -1,15 +1,45 @@
# Documentation schema for learnings written by ce:compound # Documentation schema for learnings written by ce:compound
# Treat this as the canonical frontmatter contract for docs/solutions/. # Treat this as the canonical frontmatter contract for docs/solutions/.
#
# The schema has two tracks based on problem_type:
# Bug track — problem_type is a defect or failure (build_error, test_failure, etc.)
# Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
#
# Both tracks share the same required core fields. The tracks differ in which
# additional fields are required vs optional (see track_rules below).
# --- Track classification ---------------------------------------------------
tracks:
bug:
description: "Defects, failures, and errors that were diagnosed and fixed"
problem_types:
- build_error
- test_failure
- runtime_error
- performance_issue
- database_issue
- security_issue
- ui_bug
- integration_issue
- logic_error
knowledge:
description: "Best practices, workflow improvements, patterns, and documentation"
problem_types:
- best_practice
- documentation_gap
- workflow_issue
- developer_experience
# --- Fields required by BOTH tracks -----------------------------------------
required_fields: required_fields:
module: module:
type: string type: string
description: "Module or area affected by the problem" description: "Module or area affected"
date: date:
type: string type: string
pattern: '^\d{4}-\d{2}-\d{2}$' pattern: '^\d{4}-\d{2}-\d{2}$'
description: "Date the problem was solved (YYYY-MM-DD)" description: "Date documented (YYYY-MM-DD)"
problem_type: problem_type:
type: enum type: enum
@@ -27,7 +57,7 @@ required_fields:
- workflow_issue - workflow_issue
- best_practice - best_practice
- documentation_gap - documentation_gap
description: "Primary category of the problem" description: "Primary category — determines track (bug vs knowledge)"
component: component:
type: enum type: enum
@@ -51,49 +81,6 @@ required_fields:
- tooling - tooling
description: "Component involved" 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: severity:
type: enum type: enum
values: values:
@@ -103,12 +90,99 @@ required_fields:
- low - low
description: "Impact severity" description: "Impact severity"
optional_fields: # --- Track-specific rules ----------------------------------------------------
rails_version: track_rules:
type: string bug:
pattern: '^\d+\.\d+\.\d+$' required:
description: "Rails version in X.Y.Z format" 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"
knowledge:
optional:
applies_when:
type: array[string]
max_items: 5
description: "Conditions or situations where this guidance applies"
symptoms:
type: array[string]
max_items: 5
description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
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: "Underlying cause, if there is a specific one (optional for knowledge track)"
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 change, if applicable (optional for knowledge track)"
# --- Fields optional for BOTH tracks ----------------------------------------
optional_fields:
related_components: related_components:
type: array[string] type: array[string]
description: "Other components involved" description: "Other components involved"
@@ -118,10 +192,31 @@ optional_fields:
max_items: 8 max_items: 8
description: "Search keywords, lowercase and hyphen-separated" description: "Search keywords, lowercase and hyphen-separated"
# --- Fields optional for bug track only -------------------------------------
bug_optional_fields:
rails_version:
type: string
pattern: '^\d+\.\d+\.\d+$'
description: "Rails version in X.Y.Z format. Only relevant for bug-track docs."
# --- Backward compatibility --------------------------------------------------
# Docs created before the track system was introduced may have bug-track
# fields (symptoms, root_cause, resolution_type) on knowledge-type
# problem_types. These are valid legacy docs:
# - Bug-track fields present on a knowledge-track doc are harmless. Do not
# strip them during refresh unless the doc is being rewritten for other reasons.
# - When creating NEW docs, follow the track rules above.
# --- Validation rules --------------------------------------------------------
validation_rules: validation_rules:
- "All required fields must be present" - "Determine track from problem_type using the tracks section above"
- "All shared required_fields must be present"
- "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
- "Knowledge-track docs have no additional required fields beyond the shared ones"
- "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
- "Track-specific optional fields may be included but are not required"
- "Enum fields must match allowed values exactly" - "Enum fields must match allowed values exactly"
- "symptoms must be a YAML array with 1-5 items" - "Array fields must respect min_items/max_items when specified"
- "date must match YYYY-MM-DD format" - "date must match YYYY-MM-DD format"
- "rails_version, if provided, must match X.Y.Z format" - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
- "tags should be lowercase and hyphen-separated" - "tags should be lowercase and hyphen-separated"

63
plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md
View File

@@ -7,24 +7,57 @@ Use this file as the quick reference for:
- enum values - enum values
- validation expectations - validation expectations
- category mapping - category mapping
- track classification (bug vs knowledge)
## Required Fields ## Tracks
- **module**: Module or area affected by the problem The `problem_type` determines which **track** applies. Each track has different required and optional fields.
| Track | problem_types | Description |
|-------|--------------|-------------|
| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
## Required Fields (both tracks)
- **module**: Module or area affected
- **date**: ISO date in `YYYY-MM-DD` - **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` - **problem_type**: One of the values listed in the Tracks table above
- **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` - **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` - **severity**: One of `critical`, `high`, `medium`, `low`
## Optional Fields ## Bug Track Fields
Required:
- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
- **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`
## Knowledge Track Fields
No additional required fields beyond the shared ones. All fields below are optional:
- **applies_when**: Conditions or situations where this guidance applies
- **symptoms**: Observable gaps or friction that prompted this guidance
- **root_cause**: Underlying cause, if there is a specific one
- **resolution_type**: Type of change, if applicable
## Optional Fields (both tracks)
- **rails_version**: Rails version in `X.Y.Z` format
- **related_components**: Other components involved - **related_components**: Other components involved
- **tags**: Search keywords, lowercase and hyphen-separated - **tags**: Search keywords, lowercase and hyphen-separated
## Optional Fields (bug track only)
- **rails_version**: Rails version in `X.Y.Z` format
## Backward Compatibility
Docs created before the track system may have `symptoms`/`root_cause`/`resolution_type` on knowledge-type problem_types. These are valid legacy docs:
- Bug-track fields present on a knowledge-track doc are harmless. Do not strip them during refresh unless the doc is being rewritten for other reasons.
- When creating **new** docs, follow the track rules above.
## Category Mapping ## Category Mapping
- `build_error` -> `docs/solutions/build-errors/` - `build_error` -> `docs/solutions/build-errors/`
@@ -43,8 +76,12 @@ Use this file as the quick reference for:
## Validation Rules ## Validation Rules
1. All required fields must be present. 1. Determine the track from `problem_type` using the Tracks table.
2. Enum fields must match the allowed values exactly. 2. All shared required fields must be present.
3. `symptoms` must be a YAML array with 1-5 items. 3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
4. `date` must match `YYYY-MM-DD`. 4. Knowledge-track docs have no additional required fields beyond the shared ones.
5. `rails_version`, if present, must match `X.Y.Z`. 5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
6. Enum fields must match the allowed values exactly.
7. Array fields must respect min/max item counts.
8. `date` must match `YYYY-MM-DD`.
9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.