القائمة
Use when a hard problem was just solved and the solution should be captured as a learning for future reference
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when a structured PRD document is needed for the ralph loop — generates prd.json and progress.txt
Use when task scope exceeds one context window and decomposes into independent pass/fail stories with clean iteration boundaries
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work — merge, PR, or cleanup
Use when starting feature work that needs isolation from the current workspace or before executing plans that could leave the branch in a broken state
Use when 3+ distinct occurrences suggest a skill should be updated with a new trigger, anti-pattern, or verification step
Use when creating a new skill or pattern for the dojo — guides the SKILL.md and PATTERN.md format, CSO lint rules, and index registration
| name | compound-docs |
| description | Use when a hard problem was just solved and the solution should be captured as a learning for future reference |
| tags | ["knowledge","documentation","learning"] |
| triggers | ["that worked","figured it out","the issue was","hard problem solved","lesson learned","tricky bug fixed"] |
| chains_to | ["propose-skill-update"] |
| priority | core |
| gate | false |
After solving a hard problem, propose capturing the solution as a learning. The user approves before anything is written. Learnings compound — the next time this problem appears, the solution is already documented.
After solving a hard problem, propose the learning:
"That was a non-trivial fix. Want me to capture this as a lesson learned? It'll help if this comes up again."
If the user says no, move on. No insistence.
Create a file at docs/learnings/<category>/<filename>.md:
---
date: YYYY-MM-DD
category: <category>
tags: [tag1, tag2]
---
# <Title: What the Problem Was>
## Problem
[1-3 sentences: what went wrong and how it manifested]
## Root Cause
[1-3 sentences: why it happened]
## Solution
[The fix, with code if relevant]
## Key Insight
[One sentence: the non-obvious thing that made this hard]
## References
- [Link or file:line if relevant]
Use these categories (create new ones only if none fit):
| Category | When |
|---|---|
debugging | Bug fixes, error resolution |
configuration | Setup, environment, tooling issues |
integration | API, library, service integration |
performance | Optimization insights |
architecture | Structural decisions and their outcomes |
testing | Test strategy, mocking, fixtures |
deployment | Build, deploy, CI/CD issues |
Show the proposed learning to the user. They approve before it's written to disk.
Keep the proposal concise — the learning file has the details.
If you've captured 3+ learnings about the same topic, chain to propose-skill-update — there might be a pattern worth codifying.
| Anti-Pattern | Why It's Wrong |
|---|---|
| Capturing everything | Not every fix is worth documenting. Only non-obvious ones. |
| Writing without user approval | The user decides what's worth keeping. |
| Long, essay-style learnings | Keep it scannable. Problem → Root Cause → Solution → Insight. |
| Duplicating existing learnings | Check docs/learnings/ first. Update if it already exists. |
| Capturing the "what" without the "why" | The root cause and key insight are the valuable parts. |
OPTIONAL: syntaxninja-dojo:propose-skill-update (when 3+ learnings suggest a pattern)