knowledge-architect

Knowledge Architect

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

1. Existence beats quality. Rough seed > no record. Seeds are permanent, not drafts.
2. Capture now, curate later. Messy + immediate > polished + never.
3. Discoverable > comprehensive. Invest in tags/links/indexes over content completeness.
4. Don't duplicate code. Capture what code CANNOT say: why, rejected alternatives, gotchas.
5. Design for the question. Every artifact findable by the question someone would ask.
6. Ownerless knowledge rots. Grow+ needs a human who answers "is this still true?"
7. Measure questions answered, not documents written. Still asking Slack? Discoverability is failing.
8. Use the team's tools. Best system = the one people already use.