m-sdd-knowledge

name	m-sdd-knowledge
description	SDD knowledge base — build .sdd/knowledge.md, a project-level index of facts/pointers (stack profile, file map, domain glossary, doc links, decisions) that specify and clarify read for grounding. Distinct from the constitution (rules). Triggers: sdd knowledge, knowledge base, project facts, sdd context, build knowledge, project glossary, ground specify, knowledge.md, sdd memory.

SDD — Knowledge Base

TL;DR — Draft .sdd/knowledge.md from repo discovery + context7 and generate the .sdd/repo-map.md structural layer (1) → user curates & write, recording the structural-grounding source (2) → route to specify (3). Read <skills-root>/m-sdd/_shared.md first.

Project-level facts/pointers, sibling to constitution.md. knowledge.md = what is true (facts); constitution.md = what you must do (rules). Optional and intentionally not a tracked pipeline phase — specify/clarify read it when present.

Phase 0 — Preflight

• Read <skills-root>/m-sdd/_shared.md.
• source <skills-root>/m-sdd/sdd-lib.sh; root="$(pwd)"; ensure scaffold: sdd_scaffold "$root" (copies knowledge-template.md into .sdd/templates/).
• No hard gate — knowledge is project-level and optional. If .sdd/constitution.md is absent, suggest m-sdd-constitution but proceed.

Phase 1 — Draft (assisted: discover + context7)

• Discover: scan CLAUDE.md/AGENTS.md, ARCHITECTURE.md, README, the manifest (package.json/pyproject.toml/go.mod/…), the folder layout, and the key modules. Extract a one-paragraph stack profile, a pointer map (link out — do NOT copy), and candidate glossary terms.
• Structural map (generated): run the repo-map generator to capture files + key symbols across the repo's languages: bash <skills-root>/m-sdd-knowledge/repo-map.sh "$root" → writes $root/.sdd/repo-map.md. This is the rot-proof machine layer; it replaces manual file-by-file eyeballing for structural facts. Re-runnable anytime.
• Optional code MCP: if a code-intelligence MCP is available in this session (Serena symbol tools, or CodeGraph graph tools), prefer it as the structural source — note it in the "Structural grounding" line below; the static map then serves as the offline fallback.
• External docs: for the project's main libraries, use the context7 MCP (resolve-library-id → query-docs) to gather authoritative doc links for External knowledge. If context7 is unavailable (headless/cron), skip it and record a note.
• Build a draft from .sdd/templates/knowledge-template.md.

Phase 2 — Curate & write

• Present the draft; the user edits/approves (curation, not a hard gate).
• Keep it an index of pointers, not a copy — repo facts are linked (ARCHITECTURE.md §x, path:line); glossary and decisions are written inline (they live nowhere else).
• Write the result to $root/.sdd/knowledge.md.
• Record a Structural grounding line in knowledge.md naming the active source: .sdd/repo-map.md (generated), or the MCP name (serena / codegraph).
• Ensure the target repo ignores the generated map (it is a regenerated artifact) — ask the user first (or at minimum announce it before doing it; never touch .gitignore silently): grep -qxF '.sdd/repo-map.md' "$root/.gitignore" 2>/dev/null || printf '.sdd/repo-map.md\n' >> "$root/.gitignore"

Phase 3 — Route

• Point to m-sdd-specify (next step), or m-sdd-constitution if rules aren't set yet.
• Refresh anytime by re-running this skill; it never gates the pipeline.

Never

• Duplicate repo facts into knowledge.md — link to ARCHITECTURE.md / path:line instead (a copy rots).
• Hardcode a specific stack — discover it per project (this skill is portable across repos).
• Add a knowledge phase to state.json / sdd-lib.sh — it is intentionally not state-tracked.
• Block any phase when knowledge.md is missing — it is optional; warn and proceed.
• Put binding rules here — those belong in constitution.md.
• Commit or hand-edit .sdd/repo-map.md — it is generated; regenerate via this skill.
• Duplicate symbols from repo-map.md into knowledge.md — reference, don't copy.