diff --git a/.claude/status-update-checklist.md b/.claude/status-update-checklist.md index a74ee37..55ba870 100644 --- a/.claude/status-update-checklist.md +++ b/.claude/status-update-checklist.md @@ -7,11 +7,11 @@ AI agents and developers should follow this checklist to prevent drift between f ## When to Use This Checklist -| Trigger | Scope | -|---------|-------| -| **Phase transition** (e.g., Phase 0 → Phase 1) | Full checklist — all files | -| **Milestone completed** within a phase | Sections 1–3 only | -| **Architecture decision locked** | RECOMMENDATIONS.md + new ADR in `docs/adr/` | +| Trigger | Scope | +| ---------------------------------------------- | ------------------------------------------- | +| **Phase transition** (e.g., Phase 0 → Phase 1) | Full checklist — all files | +| **Milestone completed** within a phase | Sections 1–3 only | +| **Architecture decision locked** | RECOMMENDATIONS.md + new ADR in `docs/adr/` | --- @@ -20,24 +20,34 @@ AI agents and developers should follow this checklist to prevent drift between f Run every item when the project moves to a new phase. ### 1. RULES.md + - [ ] Update section 6.2: change `Current phase: Phase N` to the new phase ### 2. README.md + - [ ] Update "Current Status" block (phase badge and status line) - [ ] Update footer status line at the bottom of the file ### 3. DOCS.md + - [ ] Update footer: `**Last Updated:** Phase N (Description)` ### 4. RECOMMENDATIONS.md + - [ ] Update `Current phase` field in section 1 -- [ ] Add entry to section 6 (Change Log) +- [ ] Update status line in header blockquote +- [ ] Update section 5 (Recommended Improvements) — remove completed items, add new recommendations +- [ ] **Run cleanup** (see RECOMMENDATIONS.md Cleanup Rules below) ### 5. docs/phases-plan.md + - [ ] Update `**Phase:**` and `**Status:**` in the header - [ ] Mark completed phase tasks as done +- [ ] Update "Current Status" section with resolved/remaining issues +- [ ] Update "Next Steps" section to reflect what's actually next ### 6. Architecture docs (if phase affects them) + - [ ] `docs/frontend/architecture.md` — lock decisions after Phase 1 - [ ] `docs/backend/architecture.md` — lock decisions after Phase 1 - [ ] Archive `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` after Phase 1 @@ -49,14 +59,62 @@ Run every item when the project moves to a new phase. Run when a significant milestone is completed within the current phase. ### 1. RECOMMENDATIONS.md -- [ ] Add entry to section 6 (Change Log) -- [ ] Update section 5 (Open Questions) — remove resolved items + +- [ ] Remove completed items from section 5 (don't strikethrough — delete them) +- [ ] Add new recommendations if audit/review produced them +- [ ] **Run cleanup** (see RECOMMENDATIONS.md Cleanup Rules below) ### 2. README.md + - [ ] Update "Current Status" block if progress indicators changed ### 3. docs/phases-plan.md + - [ ] Mark completed tasks +- [ ] Update "Current Status" section + +--- + +## RECOMMENDATIONS.md Cleanup Rules + +**Core principle:** RECOMMENDATIONS.md = "What to do next" + "Locked decisions", NOT "What we did". + +### What BELONGS in RECOMMENDATIONS.md + +- Project context and locked stack decisions (sections 1–4) +- Actionable recommendations for improvements (section 5) +- Active deployment concerns (section 6) +- ADR links (section 7) +- 1-line status summary in header blockquote (e.g., "Phase 3 complete. 16 P3 items remain.") + +### What does NOT belong in RECOMMENDATIONS.md + +- Detailed lists of completed/resolved tasks +- Strikethrough items (~~resolved item~~) — delete them, don't cross out +- Changelog / history of changes — use git history instead +- Sections titled "COMPLETE" with detailed breakdowns +- Duplicate information about accomplished work + +### Where to put completed work instead + +- **Git commit messages** — detailed implementation notes +- **docs/phases/** — phase overview files +- **docs/improvements/** — improvement summaries +- **README.md** — brief high-level status in "Current Status" section + +### When to clean up + +- Every time a phase/milestone completes (mandatory) +- If file shows strikethrough or "RESOLVED" items +- If file exceeds 200 lines (target: ~150 lines) +- If file reads like a changelog rather than a recommendations list + +### Red flags (cleanup needed) + +- Sections with ~~strikethrough~~ resolved items +- Sections titled "COMPLETE: [Detailed list]" +- Multiple paragraphs describing finished work +- Same completed work mentioned in 2+ places --- @@ -70,6 +128,9 @@ grep -rn "Phase [0-4]" RULES.md README.md DOCS.md RECOMMENDATIONS.md docs/phases # Check for stale status markers grep -rn "Status.*Draft\|Status.*WIP\|Status.*Complete" docs/ RECOMMENDATIONS.md + +# Check for strikethrough items that should have been removed +grep -rn "~~.*~~" RECOMMENDATIONS.md ``` --- @@ -80,3 +141,4 @@ grep -rn "Status.*Draft\|Status.*WIP\|Status.*Complete" docs/ RECOMMENDATIONS.md - **Concrete** — update actual sections listed above, not vague references - **Verifiable** — run the grep commands to confirm consistency - **Single source of truth** — `RULES.md` section 6.2 is the canonical phase indicator +- **Forward-looking** — RECOMMENDATIONS.md focuses on what to do next, not what was done diff --git a/RECOMMENDATIONS.md b/RECOMMENDATIONS.md index 2bcbcc4..71b1e93 100644 --- a/RECOMMENDATIONS.md +++ b/RECOMMENDATIONS.md @@ -1,69 +1,90 @@ # Project-Specific Recommendations & Overrides -This file is the project-specific layer on top of the generic template. +This file is the project-specific layer on top of the generic template. Humans and AI agents should treat it as the **single place to record locked decisions, non‑negotiable constraints, and intentional deviations** from `docs/` guidance. Update this file whenever you make a decision that changes the stack, scope, constraints, or any recommendation in `docs/`. +> **Philosophy:** This file contains **recommendations** (what to do next) and **locked decisions** (what was agreed upon). It is NOT a changelog or accomplishments log. Keep completed work in git history, `docs/phases/`, and `docs/improvements/`. + --- ## 1. Project Context (fill in) -- **Domain / product type:** _[e.g., customer support AI, compliance assistant, content classifier]_ -- **Chosen archetype:** _[A–E from `/docs/archetypes.md`]_ -- **Modules in scope:** _[core AI, integrations, pipeline, human feedback, reporting, billing, tenancy, events, queues]_ -- **Primary users:** _[roles/personas]_ -- **Key success metrics:** _[latency, accuracy, cost, adoption, etc.]_ -- **Current phase:** _Phase 0 / 1 / 2 / 3 / 4_ + +- **Domain / product type:** _[e.g., customer support AI, compliance assistant, content classifier]_ +- **Chosen archetype:** _[A–E from `/docs/archetypes.md`]_ +- **Modules in scope:** _[core AI, integrations, pipeline, human feedback, reporting, billing, tenancy, events, queues]_ +- **Primary users:** _[roles/personas]_ +- **Key success metrics:** _[latency, accuracy, cost, adoption, etc.]_ +- **Current phase:** _Phase 0 / 1 / 2 / 3 / 4_ - **Repos/services in scope:** _[monorepo, separate FE/BE, workers, etc.]_ ## 2. Locked Stack Decisions (override template here) + If a choice is not listed here, the default recommendations in `docs/` apply. **Frontend** -- **Framework:** _Next.js (App Router)_ / _other_ -- **Language:** _TypeScript_ / _other_ -- **Styling:** _Tailwind CSS_ / _other_ -- **Server/Client data layer:** _React Query / SWR / other_ -- **Forms & validation:** _React Hook Form + Zod_ / _other_ + +- **Framework:** _Next.js (App Router)_ / _other_ +- **Language:** _TypeScript_ / _other_ +- **Styling:** _Tailwind CSS_ / _other_ +- **Server/Client data layer:** _React Query / SWR / other_ +- **Forms & validation:** _React Hook Form + Zod_ / _other_ - **Auth client:** _Clerk / Auth.js / other_ **Backend** -- **Runtime/language:** _Node.js (LTS) + TypeScript_ / _other_ -- **Framework:** _Express / Fastify / other_ -- **Database:** _Postgres_ / _other_ (vector search: _pgvector_ / _other_) -- **Queues/workers:** _BullMQ (Redis)_ / _other_ -- **LLM provider & helper:** _Single abstraction (e.g., `callLLM()`)_, provider _[fill in]_ + +- **Runtime/language:** _Node.js (LTS) + TypeScript_ / _other_ +- **Framework:** _Express / Fastify / other_ +- **Database:** _Postgres_ / _other_ (vector search: _pgvector_ / _other_) +- **Queues/workers:** _BullMQ (Redis)_ / _other_ +- **LLM provider & helper:** _Single abstraction (e.g., `callLLM()`)_, provider _[fill in]_ - **File/storage:** _S3/Supabase Storage/local_ / _other_ **Infra / DevOps** -- **Hosting/deploy:** _[Vercel/Fly/K8s/etc.]_ -- **CI/CD:** _[GitHub Actions/GitLab/etc.]_ -- **Observability:** _[Sentry/OTel/Prometheus/etc.]_ + +- **Hosting/deploy:** _[Vercel/Fly/K8s/etc.]_ +- **CI/CD:** _[GitHub Actions/GitLab/etc.]_ +- **Observability:** _[Sentry/OTel/Prometheus/etc.]_ - **Environments:** _dev/stage/prod_ (or specify) ## 3. Non‑Negotiable Constraints (add to RULES scope) -- **Compliance/regulation:** _[PII/PHI/PCI, SOC2, GDPR, etc.]_ -- **Data residency/retention:** _[regions, retention window]_ -- **Performance/SLOs:** _[e.g., p95 < X ms, batch window]_ -- **Cost limits:** _[monthly LLM budget, infra cap]_ -- **Target platforms:** _[browsers/devices, locales]_ + +- **Compliance/regulation:** _[PII/PHI/PCI, SOC2, GDPR, etc.]_ +- **Data residency/retention:** _[regions, retention window]_ +- **Performance/SLOs:** _[e.g., p95 < X ms, batch window]_ +- **Cost limits:** _[monthly LLM budget, infra cap]_ +- **Target platforms:** _[browsers/devices, locales]_ - **Repository constraints:** _[additional forbidden commands, branching rules, etc.]_ ## 4. Deviations From Template (explicit trade-offs) + List any intentional departures from `docs/` recommendations and why. - _[Decision]_ → _[Why]_ → _[Migration/rollback plan if relevant]_ -## 5. Open Questions / To Confirm -- _[Unresolved item]_ → _[owner]_ → _[ETA]_ +## 5. Recommended Improvements -## 6. Change Log (optional) -- _YYYY‑MM‑DD_: _[decision summary]_ + + +_[Add audit findings, improvement suggestions, and next steps here. Group by category if needed.]_ + +## 6. Deployment Notes + + + +_[Pre-deploy checklist items, migration scripts, environment changes needed]_ ## 7. Architecture Decision Records (ADRs) + Record major decisions and their rationale in `docs/adr/`. Example ADRs you may need: + - _ADR: modular monolith vs microservices_ - _ADR: vector storage choice (pgvector vs external)_ - _ADR: billing model/provider_ @@ -71,4 +92,5 @@ Example ADRs you may need: - _ADR: auth/tenancy model_ Once accepted, link ADRs here: + - `docs/adr/0001-