{slug}-design.md

{slug}-fix-note.md

• Pitfall track: Record the problems encountered, root causes, and solutions to avoid falling into the same traps next time
• Knowledge track: Record discovered best practices, workflow improvements, and reusable patterns

codestable/compound/

codestable/reference/shared-conventions.md

doc_type: learning

YYYY-MM-DD-learning-{slug}.md

learning

• Source type: Feature workflow / Issue workflow / Independent problem
• Associated artifacts: Feature directory path / Issue directory path (if available, for reference in the document's "source" field)
• Track classification: Pitfall or knowledge. Judgment criteria — "fixed something that was broken" = pitfall; "discovered a better approach" = knowledge. If both are present, write two separate documents.

codestable/reference/shared-conventions.md

• If the user's message includes phrases like "modify / update / supplement / a specific learning" or clearly refers to an old document → directly follow the update existing entry path
• Otherwise, use the "Search Tool" below with

  --filter tags~=

  or

  --query

  to search for the current topic / component. If similar old documents are found, present the candidates to the user and let them choose: update / supersede / truly different topic

updated: YYYY-MM-DD

1. "What was the initial phenomenon you observed?"
2. "Which solutions did you try that didn't work?" (Encourage users to write this even if they think it's "nothing" — failed attempts are the most valuable information for future team members; knowing which paths don't work can save a lot of time)
3. "How did you finally identify the real cause?"
4. "Can this be detected earlier next time? How?"

1. "In what scenarios is this pattern you discovered most valuable?"
2. "What problems would arise if this approach is not followed?"
3. "Are there any counterexamples where this does not apply?"

• AI drafts the complete learning document (including YAML frontmatter + all body sections)
• Present the full draft to the user for review at once
• Write to the file after user confirmation; adjust according to user feedback if there are modifications

• New document path: Write to

  codestable/compound/

  , name the file

  YYYY-MM-DD-learning-{slug}.md

  (use the archive date, not the date the problem occurred), include

  doc_type: learning

  at the top of the frontmatter (see

  reference.md

  )
• Update path: Write back to the original file located in Phase 1.5, add

  updated: YYYY-MM-DD

  to the frontmatter
• Supersede path: Handle the old and new files in accordance with Section 5 of

  shared-conventions.md

  §6
• Report the complete file path after writing

Complete syntax and examples can be found in

codestable/reference/tools.md

. This section only lists typical queries specific to learning documents.

undefined

Shared guard rules for archiving workflows (add-only, quality over quantity, do not write on behalf of users, discoverability, check for duplicates after archiving) can be found in Section 6 of

codestable/reference/shared-conventions.md

. Rules specific to this skill:

1. Do not mix with spec — learning documents are not spec documents, and should not be placed in

   features/

   or

   issues/

   ; spec documents should also not be placed in

   codestable/compound/

2. Only recognize own doc_type — only read and write documents with

   doc_type: learning

   , and do not perceive other doc_type documents in the

   compound/

   directory