From 739109c03ccd45474331625f35730924d17f63ef Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Sun, 29 Mar 2026 14:21:13 -0700 Subject: [PATCH] feat(ce-compound): add track-based schema for bug vs knowledge learnings (#445) Co-authored-by: Claude Opus 4.6 (1M context) --- .../assets/resolution-template.md | 53 +++++ .../references/schema.yaml | 203 +++++++++++++----- .../references/yaml-schema.md | 63 ++++-- .../skills/ce-compound/SKILL.md | 44 ++-- .../ce-compound/assets/resolution-template.md | 53 +++++ .../skills/ce-compound/references/schema.yaml | 203 +++++++++++++----- .../ce-compound/references/yaml-schema.md | 63 ++++-- 7 files changed, 529 insertions(+), 153 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md b/plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md index 9e06208..c7a03d4 100644 --- a/plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md +++ b/plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md @@ -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] date: [YYYY-MM-DD] @@ -35,3 +46,45 @@ tags: [keyword-one, keyword-two] ## Related Issues - [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] +``` diff --git a/plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml b/plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml index ebf2438..32d1509 100644 --- a/plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml +++ b/plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml @@ -1,15 +1,45 @@ # Documentation schema for learnings written by ce:compound # 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: module: type: string - description: "Module or area affected by the problem" + description: "Module or area affected" date: type: string pattern: '^\d{4}-\d{2}-\d{2}$' - description: "Date the problem was solved (YYYY-MM-DD)" + description: "Date documented (YYYY-MM-DD)" problem_type: type: enum @@ -27,7 +57,7 @@ required_fields: - workflow_issue - best_practice - documentation_gap - description: "Primary category of the problem" + description: "Primary category — determines track (bug vs knowledge)" component: type: enum @@ -51,49 +81,6 @@ required_fields: - 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: @@ -103,12 +90,99 @@ required_fields: - low description: "Impact severity" -optional_fields: - rails_version: - type: string - pattern: '^\d+\.\d+\.\d+$' - description: "Rails version in X.Y.Z format" +# --- Track-specific rules ---------------------------------------------------- +track_rules: + bug: + required: + 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: type: array[string] description: "Other components involved" @@ -118,10 +192,31 @@ optional_fields: max_items: 8 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: - - "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" - - "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" - - "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" diff --git a/plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md b/plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md index abc7b69..f1f323d 100644 --- a/plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md +++ b/plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md @@ -7,24 +7,57 @@ Use this file as the quick reference for: - enum values - validation expectations - 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` -- **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` -- **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 +## 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 - **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 - `build_error` -> `docs/solutions/build-errors/` @@ -43,8 +76,12 @@ Use this file as the quick reference for: ## 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. Determine the track from `problem_type` using the Tracks table. +2. All shared required fields must be present. +3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs. +4. Knowledge-track docs have no additional required fields beyond the shared ones. +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. diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index f1a2df2..b162093 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -75,24 +75,24 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator. #### 1. **Context Analyzer** - 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 - - Reads `references/schema.yaml` for enum validation + - Reads `references/schema.yaml` for enum validation and **track classification** + - Determines the track (bug or knowledge) from the problem_type + - 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/` - 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 force bug-track fields onto knowledge-track learnings or vice versa #### 2. **Solution Extractor** - - Analyzes all investigation steps - - Identifies root cause - - Extracts working solution with code examples + - Reads `references/schema.yaml` for track classification (bug vs knowledge) + - Adapts output structure based on the problem_type track - 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 - **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 - **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** - Searches `docs/solutions/` for related documentation - 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: -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**: 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) - - Solution with key code snippets - - One prevention tip +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 track (bug vs knowledge), category, and filename +3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with: + - YAML frontmatter with track-appropriate fields + - Bug track: Problem, root cause, solution with key code snippets, one prevention tip + - Knowledge track: Context, guidance with key examples, one applicability note 4. **Skip specialized agent reviews** (Phase 3) to conserve context **Compact-safe output:** diff --git a/plugins/compound-engineering/skills/ce-compound/assets/resolution-template.md b/plugins/compound-engineering/skills/ce-compound/assets/resolution-template.md index 9e06208..c7a03d4 100644 --- a/plugins/compound-engineering/skills/ce-compound/assets/resolution-template.md +++ b/plugins/compound-engineering/skills/ce-compound/assets/resolution-template.md @@ -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] date: [YYYY-MM-DD] @@ -35,3 +46,45 @@ tags: [keyword-one, keyword-two] ## Related Issues - [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] +``` diff --git a/plugins/compound-engineering/skills/ce-compound/references/schema.yaml b/plugins/compound-engineering/skills/ce-compound/references/schema.yaml index ebf2438..32d1509 100644 --- a/plugins/compound-engineering/skills/ce-compound/references/schema.yaml +++ b/plugins/compound-engineering/skills/ce-compound/references/schema.yaml @@ -1,15 +1,45 @@ # Documentation schema for learnings written by ce:compound # 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: module: type: string - description: "Module or area affected by the problem" + description: "Module or area affected" date: type: string pattern: '^\d{4}-\d{2}-\d{2}$' - description: "Date the problem was solved (YYYY-MM-DD)" + description: "Date documented (YYYY-MM-DD)" problem_type: type: enum @@ -27,7 +57,7 @@ required_fields: - workflow_issue - best_practice - documentation_gap - description: "Primary category of the problem" + description: "Primary category — determines track (bug vs knowledge)" component: type: enum @@ -51,49 +81,6 @@ required_fields: - 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: @@ -103,12 +90,99 @@ required_fields: - low description: "Impact severity" -optional_fields: - rails_version: - type: string - pattern: '^\d+\.\d+\.\d+$' - description: "Rails version in X.Y.Z format" +# --- Track-specific rules ---------------------------------------------------- +track_rules: + bug: + required: + 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: type: array[string] description: "Other components involved" @@ -118,10 +192,31 @@ optional_fields: max_items: 8 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: - - "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" - - "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" - - "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" diff --git a/plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md b/plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md index abc7b69..f1f323d 100644 --- a/plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md +++ b/plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md @@ -7,24 +7,57 @@ Use this file as the quick reference for: - enum values - validation expectations - 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` -- **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` -- **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 +## 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 - **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 - `build_error` -> `docs/solutions/build-errors/` @@ -43,8 +76,12 @@ Use this file as the quick reference for: ## 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. Determine the track from `problem_type` using the Tracks table. +2. All shared required fields must be present. +3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs. +4. Knowledge-track docs have no additional required fields beyond the shared ones. +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.