knowledge-architecture

Knowledge Architecture Skill

Purpose

Create a durable, file-backed knowledge system that helps the team keep shared context, decisions, rules, and open questions in one place.

This milestone is static-first:

• no hooks
• no MCP
• no custom tools
• no runtime memory engine

Use markdown files, links, and clear ownership.

When to Use

• Starting a knowledge base for a product or domain
• Reorganizing scattered planning notes into canonical files
• Turning repeated context into stable rules and references
• Establishing decision, quality, and review links around a domain

Canonical Inputs

• templates/knowledge/index.md
• templates/knowledge/domain.md
• templates/knowledge/knowledge.md
• templates/knowledge/hypotheses.md
• templates/knowledge/rules.md
• docs/knowledge/README.md

Related records:

• templates/decisions/decision.md
• templates/quality/gate.md
• templates/review/maintenance-review.md

Target Structure

Prefer this shape:

docs/knowledge/
├── README.md
├── index.md
├── domains/
│   └── <domain>.md
├── entries/
│   └── <topic>.md
├── hypotheses.md
└── rules.md

Workflow

1. Define scope

   • What product, system, or domain does this cover?
   • What should be durable vs still uncertain?

2. Create the index

   • Start from templates/knowledge/index.md.
   • Capture domains, key knowledge, rules, open hypotheses, and linked records.

3. Map domains

   • Create one file per meaningful domain from templates/knowledge/domain.md.
   • Keep boundaries explicit.

4. Capture atomic knowledge

   • Use templates/knowledge/knowledge.md for durable facts, patterns, or references.
   • Favor small entries with strong links.

5. Track uncertainty

   • Use templates/knowledge/hypotheses.md for claims that need validation.
   • Every hypothesis should have an owner or next validation step.

6. Write rules

   • Use templates/knowledge/rules.md for stable operating rules.
   • Link each rule to evidence, decisions, or prior incidents when possible.

7. Link adjacent systems

   • Stable choices belong in docs/decisions/.
   • Repeatable checks belong in docs/quality/.
   • Recurring health checks belong in docs/reviews/maintenance/.

Writing Rules

• Keep titles crisp.
• Prefer one idea per file.
• Mark uncertainty instead of hiding it.
• Link laterally across knowledge, decisions, quality, and reviews.
• Avoid session-specific chatter.

Done Criteria

• docs/knowledge/index.md exists or is updated.
• Core domains are listed.
• Durable knowledge is separated from hypotheses.
• Rules are explicit.
• Related decisions, gates, and reviews are linked.

Anti-Patterns

• Giant undifferentiated notes
• Rules without rationale
• Decisions embedded in random meeting notes
• Hypotheses presented as settled facts
• Runtime tooling assumptions in milestone 1

Anti-Rationalization Table

Excuse	Counter
"We can organize the knowledge base later"	Disorganized knowledge is lost knowledge. Structure it while the context is fresh.
"One big document is easier to maintain"	Giant undifferentiated notes are impossible to navigate. Split by domain.
"Hypotheses should be marked as facts for clarity"	Marking uncertainty as fact corrupts the knowledge base. Be honest about what is known.
"Rules don't need rationale"	Rules without rationale are ignored. Explain the why behind each rule.
"We don't need a knowledge base for this project"	Every project accumulates knowledge. Without a home for it, it lives in people's heads.