learnwy Knowledge Consolidation
Project-local fix journal. One conversation → one structured Markdown file in this repo's IDE folder. Stays with the codebase; ships in the repo; future sessions on this project can find it.
Boundary: project-local debugging/config/workflow/lesson notes belong here. Global, reusable knowledge (architectures, design patterns, API integrations, references) belongs in llm-wiki. KC's
promotecommand moves a doc across the seam when it earns its way into the wiki.
When to use
| Trigger | Action |
|---|---|
| User says "save this", "记录下来", "we solved it" | Run cli.cjs save … |
| Stop nudge fired ("looks like you resolved a non-trivial problem") | Offer to save |
| Solved a bug specific to this codebase | --type debug |
| Locked in a non-obvious config / build setting | --type config |
| Established an ops procedure (deploy / rollback) | --type workflow |
| Post-mortem / retrospective takeaway | --type lesson |
Do not use for: cross-project knowledge (→ llm-wiki), reusable skills (→ project-skill-writer), AI rules (→ project-rules-writer), updating a previously saved doc (KC is write-once).
Prerequisites
- Node.js ≥ 18
- Project root contains an IDE marker dir:
.trae/,.claude/,.cursor/, or.windsurf/
The one command you usually want
node scripts/cli.cjs save \
-r <project_root> \
-a <ai_type> \
-t <type> \
-n <kebab-slug> \
--title "Short, specific title" \
--summary "2-3 sentences readers can stop at" \
--details "Body in Markdown." \
--takeaways "First actionable insight\nSecond insight" \
[--background "<one-line problem context>"] \
[--context "<project / version / component>"] \
[--related "<links / files>"]
Returns the absolute path of the new file. Atomically resolves a date-sequenced name, creates the directory, fills the template, validates required fields.
-a, --ai-type |
trae, trae-cn, claude-code (or claude), cursor, windsurf |
|---|---|
-t, --type |
debug, config, workflow, lesson only — see knowledge-types.md |
-n, --name |
kebab-case slug, ≤50 chars, specific (react-18-hydration-mismatch, not bug-fix) |
Output filename: {YYYYMMDD}_{NNN}_{type}_{slug}.md under <root>/<ide>/knowledges/.
Promote to global wiki
When a doc turns out to be reusable across projects, push it into llm-wiki's ingestion queue:
node scripts/cli.cjs promote -p <project>/.trae/knowledges/20260511_001_debug_x.md
Copies into ~/.learnwy/llm-wiki/raw/notes/<date>-<slug>.md with a frontmatter pointer back to the original. No-op if the wiki isn't initialised. Run llm-wiki's ingestion next.
Other commands
node scripts/cli.cjs path -r <root> -a <ai> -t <type> -n <name>
# → just prints the resolved path; useful for scripts that want to write the file themselves.
Stop hook (auto-nudge)
A Stop hook scans the assistant's last response for resolution signals ("the bug was…", "fixed it", "## Solution"). If it fires AND the response shows substantive markers (race condition, regression, design decision, "subtle", etc.) AND no session-local trivia markers (typo, missing semicolon, wrong env var), it injects a one-time per-session nudge: "consider running knowledge-consolidation save".
The hook never auto-writes. It nudges; the AI asks the user.
The hook is wired through learnwy-dispatch (single Node process, no per-skill spawn).
Writing-quality rules
- Title answers "what can I learn from this?" — not "Debug session" but "Memory leak in WebSocket reconnect handler".
- Summary is self-contained — readers decide whether to keep going.
- Details code blocks have language tags; long content uses sub-headers.
- Takeaways are imperative — "Always check X before Y", not "X is important".
- Related links to source files, PRs, or
[[wiki-page]]references where applicable.
Boundaries
This skill only:
- Detects the IDE marker and resolves a unique knowledge-doc path
- Atomically writes a structured doc from CLI args
- Promotes a doc into the global llm-wiki ingestion queue
- Surfaces a Stop nudge once per session when a non-trivial problem is resolved
This skill does not:
- Update existing docs (write-once on purpose)
- Index / lint / curate (that's llm-wiki)
- Save AI memory across sessions
- Search past knowledge docs