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. --- docs/learnings/grasp-01-implementation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/learnings/grasp-01-implementation.md') 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