| name | knowledge-architect |
|---|---|
| description | Apply whenever knowledge is at risk of being lost, needs to be captured, or a team needs to design how knowledge flows and persists. Triggers on 'document this decision', 'we should write this down', 'someone is leaving the team', 'why did we do it this way?', 'we keep re-debating this', 'set up our knowledge system', 'our docs are a mess', 'onboarding is painful', or any situation where implicit knowledge needs to become explicit and discoverable. Also trigger after incidents, migrations, vendor choices, or finished spikes — high-value capture moments. |
Core principle: Knowledge that isn't discoverable isn't captured — it's just written down. Capture close to the moment (context fresh) but serve a reader far from it (months later, different person). Every design decision resolves that tension.
| Mode | Trigger | Output |
|---|---|---|
| Capture | User has something specific to capture | Knowledge artifact at right format/depth |
| Detect | Workflow moment puts knowledge at risk | Capture prompt + draft artifact |
| Design | User wants to set up/improve knowledge systems | Architecture: where, how found, who owns |
Default to Capture if unclear.
| Type | Question | Audience | Shelf life |
|---|---|---|---|
| Decision | "Why X over Y?" | Future-self, new members | Long — until superseded |
| Context | "What would I wish someone told me?" | New member | Medium — periodic refresh |
| Learning | "What did we learn the hard way?" | Anyone facing same situation | Variable — until system changes |
"why did we do it this way?" → Decision
"I wish someone had told me" → Context
"we learned this the hard way"→ Learning
Multiple types → match PRIMARY reader need
| Depth | Time | Output | When |
|---|---|---|---|
| Seed | 2 min | 2-5 sentences: what, why, one insight | Default. A seed > a doc that doesn't exist. |
| Grow | 15 min | Structured artifact + discovery header | Reusable, multi-person, significant consequences |
| Curate | 30 min | Polished reference + examples + edge cases | Architectural decisions, critical procedures, cross-team rules |
Always start at Seed. Promote when someone needs more.
## Decision: [verb phrase]
**Date**: [date] | **By**: [who] | **Status**: Active
[What decided, why, "why not" for the most obvious alternative.]
## Decision: [What was decided]
**Date**: [date] | **Deciders**: [who] | **Status**: Active | Superseded by [link]
**Tags**: [tags] | **Review trigger**: [when to revisit]
### Context
[Situation + constraints. Write for ZERO-context reader.]
### Decision
[1-2 sentences.]
### Alternatives Considered
- **[Alt A]**: [Why not] | **[Alt B]**: [Why not] | **Do nothing**: [Why not]
### Consequences
[Easier / harder / risks accepted]
### Related
[Decisions, PRs, docs, threads]
Curate adds: Decision History (supersession chain), Applicability (when applies/doesn't), Verification (how to check compliance).
## Context: [What this is about]
**Area**: [system/domain/team] | **Owner**: [who knows most]
[What a new person needs to know. Prioritize the non-obvious.]
## Context: [What this is about]
**Area**: [scope] | **Owner**: [who] | **Last verified**: [date] | **Tags**: [tags]
### The Rule — [one paragraph max]
### Why This Exists — [what goes wrong if ignored; real examples]
### Common Mistakes — [misconceptions, reasonable-looking shortcuts that break things]
### Exceptions — [when it doesn't apply]
### Who to Ask — [primary + backup]
### Related
## Learning: [One-sentence summary]
**Date**: [date] | **Source**: [incident / migration / spike]
[What happened, what we discovered, what to do differently. Transferable insight, not narrative.]
## Learning: [One-sentence summary]
**Date**: [date] | **Source**: [link] | **Applicability**: [systems/situations]
**Tags**: [tags] | **Confidence**: High / Medium / Low
### What Happened — [3-5 sentences, not a full post-mortem]
### What We Learned — [principle, not story: "X causes Y" not "last Tuesday X happened"]
### Recommendation — [specific, actionable: "Do X" not "Be careful with X"]
### Caveats — [when this doesn't apply]
### Evidence — [incidents, dashboards, PRs]
Every Grow+ artifact gets:
type: decision | context | learning
tags: [flat, consistent vocabulary — nouns/domains, not adjectives]
area: [system/domain/team]
owner: [person/team]
created: [date]
last_verified: [date]
review_trigger: [condition or date]
status: active | superseded | archived
related: [links]Tags answer: "what would someone search for when they need this?"
| Moment | At risk | Capture |
|---|---|---|
| PR merged (significant design) | Why approach was chosen | Decision — Seed |
| Incident resolved | Debugging insights, root cause | Learning — Grow |
| Team member leaving | Tribal knowledge, conventions | Context — Grow (multiple) |
| New member joining | Doc gaps | Context audit (run context-gap-analyzer) |
| Vendor/tool selected | Criteria, trade-offs, rejections | Decision — Grow |
| Migration completed | Gotchas, unexpected behaviors | Learning — Grow |
| Spike finished | Findings, dead ends | Learning — Seed/Grow |
| Repeated Slack question | Undocumented common knowledge | Context — Seed |
| Decision re-debated | Original reasoning lost | Decision — Grow (retroactive) |
| Workaround established | Why exists, removal trigger | Context — Seed |
| Process changed | Why old failed, how new differs | Decision — Grow |
CAPTURE MOMENT DETECTED
I notice [what happened].
At risk: [what may be lost]
Suggested: [Type] — [Depth] (~[time])
Want me to draft from available context?
Draft from PRs, incidents, conversation. User edits rather than writes from scratch.
Where knowledge lives today; what's discoverable; what's broken ("I can never find..."); team size; existing tools. Inventory which capture moments produce artifacts vs. don't. Estimate knowledge debt volume.
Four components:
1. Location — Closest to where used.
- Decisions → repo
/docs/decisions/(travels with code) - System context → repo (humans + agents)
- Domain/team context → wiki/Notion (spans repos)
- Learnings → repo for single-system, wiki for cross-system
- Onboarding → curated index that LINKS (not duplicates)
Adapt to team's tools. Best location = the one people already go to.
2. Discovery — Three channels:
- Search: flat tag vocabulary, README indexes, platform search
- Browse: directory mirrors team/domain boundaries, area indexes
- Stumble: link from PRs/incidents/code comments; "Related" links in every Grow+ artifact
3. Ownership — Every artifact has exactly one owner. Ownerless artifacts rot.
- Assign per team/area. Learnings owned by capturer until transferred.
- Departing members: knowledge transfer + Detect mode run.
- Quarterly orphan audit: flag unowned for adoption or archival.
4. Freshness — Outdated knowledge is worse than none.
- Time-based: context reviewed every 6 months
- Event-based: decisions reviewed when system changes
- Query-based: readers flag inaccuracies
- Every artifact has
last_verified. >12 months = STALE → refresh, archive, or delete.
| Phase | What | Effort |
|---|---|---|
| Week 1-2 | Seed top 10 undocumented decisions + 5 common new-hire questions. Set up directories. | ~2 hours |
| Week 3-4 | Add capture to incident definition-of-done + retro agendas. Grow 3-5 highest-value seeds. | ~1 hr/week |
| Month 2-3 | Assign owners. First quarterly health check. Onboarding index. | ~2 hours |
| Ongoing | Capture at workflow moments (2 min). Grow when reused (15 min). Quarterly check (30 min). | Maintenance |
- Existence beats quality. Rough seed > no record. Seeds are permanent, not drafts.
- Capture now, curate later. Messy + immediate > polished + never.
- Discoverable > comprehensive. Invest in tags/links/indexes over content completeness.
- Don't duplicate code. Capture what code CANNOT say: why, rejected alternatives, gotchas.
- Design for the question. Every artifact findable by the question someone would ask.
- Ownerless knowledge rots. Grow+ needs a human who answers "is this still true?"
- Measure questions answered, not documents written. Still asking Slack? Discoverability is failing.
- Use the team's tools. Best system = the one people already use.