From 8c129a4aeab3288f8193ccb820adf00860c50d74 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Thu, 4 Dec 2025 15:45:48 +0000 Subject: docs: add guidance to keep architecture docs updated - Added CRITICAL warning section to AGENTS.md about treating architecture docs as living documents - Mark 'Keep Architecture Docs Updated' item as fixed in grasp-01 learnings - Mark 'Document actual architecture' technical debt item as fixed This addresses a key learning from GRASP-01 where docs described plans rather than implementation, causing confusion. --- AGENTS.md | 11 +++++++++++ docs/learnings/grasp-01-implementation.md | 6 ++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 236602b..6fbec69 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -172,6 +172,17 @@ fn test_audit_tags_automatically_added() { ## Documentation +**⚠️ CRITICAL: Keep Architecture Docs Updated** + +Architecture and design documents are LIVING DOCUMENTS. When implementation diverges from the documented plan: + +1. **Update the doc IMMEDIATELY** - Don't wait until "later" +2. **Document what was actually built**, not what was originally planned +3. **Note why decisions changed** - Future readers need this context +4. **Files to watch:** `docs/explanation/architecture.md`, `docs/explanation/decisions.md` + +This was a key learning from GRASP-01: docs described plans, not implementation, causing confusion. + **Diátaxis Framework Used:** - `docs/tutorials/` - Learning-oriented diff --git a/docs/learnings/grasp-01-implementation.md b/docs/learnings/grasp-01-implementation.md index 719f751..14ab452 100644 --- a/docs/learnings/grasp-01-implementation.md +++ b/docs/learnings/grasp-01-implementation.md @@ -150,12 +150,14 @@ This enables parallel CI runs without interference. ## What I'd Do Differently -### 1. Keep Architecture Docs Updated +### 1. ~~Keep Architecture Docs Updated~~ ✅ FIXED **What happened:** Architecture design docs were essential to start - they guided the implementation. But as we made decisions (e.g., hyper instead of actix-web), the docs weren't updated to reflect reality. **Better approach:** Treat architecture docs as living documents. When implementation diverges from the plan, update the doc immediately. The initial design document was valuable and should remain, but it should reflect what was built. +**Resolution:** Added prominent warning to [`AGENTS.md`](../../AGENTS.md) with explicit guidance to keep architecture docs updated as living documents. + ### 2. ~~Smaller Nip34WritePolicy~~ ✅ DONE **What happened:** The `Nip34WritePolicy` grew to ~900 lines handling all event types. @@ -192,7 +194,7 @@ The main [`Nip34WritePolicy`](src/nostr/builder.rs:51) now delegates to these su 1. ~~**Split `Nip34WritePolicy`**~~ ✅ DONE - Split into sub-policies in [`src/nostr/policy/`](src/nostr/policy/mod.rs:1) 2. **Add unit tests for policy logic** - Currently relies on integration tests -3. **Document actual architecture** - Docs describe plans, not implementation +3. ~~**Document actual architecture**~~ ✅ FIXED - Added guidance to AGENTS.md to keep docs updated as living documents ### Medium Priority -- cgit v1.2.3