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.
STEP 1 — Detect the Mode
| 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.
MODE 1: CAPTURE
STEP C1 — Classify Type
| 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
STEP C2 — Choose Depth
| 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.
STEP C3 — Produce Artifact
DECISION — Seed
## Decision: [verb phrase]
**Date**: [date] | **By**: [who] | **Status**: Active
[What decided, why, "why not" for the most obvious alternative.]
DECISION — Grow
## 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 — Seed
## 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 — Grow
## 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 — Seed
## Learning: [One-sentence summary]
**Date**: [date] | **Source**: [incident / migration / spike]
[What happened, what we discovered, what to do differently. Transferable insight, not narrative.]
LEARNING — Grow
## 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]
STEP C4 — Discovery Header
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?"
MODE 2: DETECT
Capture Moments
| 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 |
Detection Prompt
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.
MODE 3: DESIGN
STEP D1 — Audit
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.
STEP D2 — Design Architecture
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.
STEP D3 — Bootstrap Plan
| 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 |
Calibration
- 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.