cs-learn

cs-learn

Must-read at startup

Before making any judgment or taking any action, first read .codestable/attention.md; if missing, treat it as an incomplete skeleton, prompt to fill it in first or run cs-onboard, and do not fall back to external AI entry files.

Every time you do a feature or fix an issue, a spec file is left behind. But the spec records "what was done" and "how it was done",it does not record "what pitfalls were encountered" and "what better approaches were discovered". A team without consolidation keeps solving the same problem over and over.

Two tracks:

• Pitfall track(pitfall): record problem / root cause / solution, to prevent falling into the same pit next time
• Knowledge track(knowledge): record best practices / workflow improvements / reusable patterns

Both are written to .codestable/compound/(for the shared directory see shared-conventions.md section 1 "Archival documents"). This skill produces frontmatter with doc_type: learning, named YYYY-MM-DD-learning-{slug}.md。

---

When to trigger

Situation	Description
Completing a feature workflow	cs-feat-accept proactively ask "Do you want to record the learning points from this time?"
Completing an issue workflow	cs-issue-fix proactively ask "Do you want to record this pitfall?"
User initiative	"record this", "consolidate knowledge", "learning", etc.
Solved a one-off difficult problem	an engineering problem not within a feature / issue but that took a lot of time to solve

Proactively recommending it with one sentence is enough; if the user says "no need", skip immediately—repeated pushing may make the user feel the AI is adding drama.

---

What each of the two tracks writes

Pitfall: bugs debugged / configuration traps bypassed / environment issues / integration failures……all experiences of "it should have worked but didn't".

Knowledge: best practices discovered / workflow improvements / architectural insights / reusable design patterns……all learnings of "this should be the default way going forward".

For frontmatter / body template / complete examples see the same directory reference.md。

---

Workflow stages

Phase 1: Identify the source (automatic)

Extract from the conversation context:

• Source type: feature workflow / issue workflow / standalone problem
• Associated artifact: feature directory / issue directory path (if any)
• Rough track classification: pitfall or knowledge. "Fixed something broken" = pitfall; "discovered a better approach" = knowledge. If both, split into two entries

If the source is unclear, ask the userone questionClarify, do not guess.

Phase 1.5: Check for overlap and route by intent (mandatory)

According to shared-conventions.md §6 items 5/6:

• Contains "modify / update / supplement / a certain learning" or points to an old document → go directly toupdate existing
• Otherwise use a search tool to search by --filter tags~= or --query , and when a similar old document is hit, list the candidates to the user

Update path: Read the old document → align with the user on which sections to change (commonly adding newly encountered pitfalls and adding the root cause of what was "unable to find the cause" at the time) → draft the diff → write back to the original file + updated: YYYY-MM-DD, do not create a new one.

Phase 2: Distill key points (one question at a time)

Pitfall trackAsk:

1. "What was the phenomenon you first observed?"
2. "Which solutions did you try that didn't work?" (encourage writing; failed attempts are the most valuable information for those who come later — knowing which path is a dead end can save a lot of time)
3. "How did you finally discover the real cause?"
4. "Could it have been discovered earlier next time? How?"

Knowledge trackAsk:

1. "In what situations is this pattern you discovered most valuable?"
2. "What problems arise if you don't do it this way?"
3. "Are there any counterexamples where it doesn't apply?"

If the user says "nothing" or "skip" about a question, skip it — better to have one fewer section than to fill it with empty words.

Phase 3: Draft + user review

The AI drafts the complete document in one go (YAML frontmatter + all body sections). Show it to the user all at once.

Phase 4: Archive

• Create: write to compound/YYYY-MM-DD-learning-{slug}.md(date is thearchive day), frontmatter carries doc_type: learning
• Update: write back to the original file located in Phase 1.5 + updated: YYYY-MM-DD
• supersede: handle according to shared-conventions.md §6 item 5

Phase 5: Discoverability check

After writing, if you find one or two lines of project hard constraints that "every CodeStable skill startup should know", prompt the user to use cs-note to append to .codestable/attention.md. Do not change attention on your own initiative, and do not write an external AI entry point.

---

Search tool

For the full syntax see .codestable/reference/tools.md。

# 按轨道筛选坑点

python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter track=pitfall --filter severity=high

# 按组件查相关学习点

python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter component~={组件名}

# 归档后查重叠

python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter tags~={主要 tag} --json

---

Guard rules

For shared archiving rules see shared-conventions.md Section 6. Specific to this skill:

1. Do not mix into spec——learning does not go into features/ or issues/; spec also does not go into compound/
2. Only recognize its own doc_type——only read and write doc_type: learning