💡 Idea Validation: For architect role i have created a list of checklist to follow before creating SPINE document #2676
Replies: 1 comment 2 replies
|
Validating from experience running a similar setup. The structure you've landed on (a reusable checklist the role consumes, answers flowing to per-project files) matches a boundary we've found worth enforcing explicitly. The checklist stays pure method (questions, constraints, red flags) with zero project facts, and everything project-specific lives only in the per-project artifacts, your The failure mode that creeps in otherwise is checklist rot. A correction made during project A's verify pass gets folded into the "reusable" file as an answer rather than a better question, and every later project silently inherits project A's assumptions. A cheap guard is a lint that fails the checklist file if it ever contains a One suggestion on the prefill step: keep the I maintain a reference architecture that documents this role/facts split: https://github.com/jimy-r/agent-workspace-architecture/blob/main/PATTERNS.md#1-pure-roles-composed-with-project-facts |
|
Thanks for the detailed breakdown — I don't have much experience in this space, so it took me a few passes (re-reading it multiple times) to fully follow what you were describing. Appreciate you laying it out so clearly, and I'm more than happy to be corrected if my thinking below is off. Going through your reference architecture, what stood out is that you have a solid checklist / code-of-conduct style file that gets referenced to shape the model's initial behavior. That's what pushed me to realize I need to build my own curated module along similar lines, using your learnings doc as the reference point. To state my actual problem more directly: I don't mind if the final artifact ends up as a single "spine" document — if anything, that's better for agent consumption. My concern is with the process of getting there. Working through it as a pure questionnaire, incrementally, isn't easy to follow or answer as a human. At the same time, I don't want to just hand the agent the test condition and let it loop until it converges — sure, it can do that, but it burns a lot of tokens for something a human could resolve faster. What I'd rather have is a workflow with a human checkpoint built in — something closer to a traditional flow, expressed as a diagram (e.g. in Excalidraw), that's easy for a person to review. If something needs updating, you edit the diagram and feed that back in, rather than going back and forth with the agent purely through text. Once implemented, that diagram becomes disposable — or at most it moves into That said, I'm second-guessing whether these intermediate artifacts add real value at all, since the code itself is the source of truth. Curious whether you see a substantial benefit in keeping them around, or if that's exactly the "checklist rot" risk you flagged above. |
|
The test I use for an intermediate artifact is whether anything will read it later and treat it as current. That splits your question cleanly. The diagram as a human checkpoint is worth having, because it captures the one thing code never records, which is why this shape was chosen and what was ruled out. But it earns its keep as a dated decision record, not a living document. Move it to docs/ with a date, treat it as history, and let it go stale honestly. Staleness only becomes rot when a file gets re-consumed as authority. That is why the reusable checklist needs strict hygiene while a per-project artifact doesn't. So keep the intent record, which is cheap and stops you re-litigating settled decisions with the agent later, and discard or regenerate anything that merely restates what the code now shows. If a diagram describes structure the code already expresses, regenerate it from code when needed rather than maintaining it by hand. Method files never absorb project facts, and project records never pretend to be current. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Go through Checklist Section which has my prompt; currently i use it as a separate method by calling Bmad-Architecture-Discovery but felt like this is very common things to go through each time sometimes you forget to address some of them; so I created this checklist.
I wanted to validate this idea before making changes and raise a pull request.
Checklist File
BMAD Architecture Discovery Checklist
A reusable reference for running
bmad-architecturewith full coverage instead of relying on memory. Feed this whole file to the Architect as your scope brief, or use it yourself to review its output.The Workflow
prd.md(+ux-spec.md,project-context.mdif present) and draft a first-pass answer for every section below into a scratch file:architecture-discovery.md. Every answer starts tagged[DRAFT - from PRD]or[UNKNOWN - needs your input]. Nothing here is trusted yet.[VERIFIED]. Generate the diagram for that section now, while the decision is fresh, not in a batch at the end.[VERIFIED], the confirmed content moves intoARCHITECTURE-SPINE.md(decisions + rules) andproject-context.md(implementation rules for downstream agents). Diagrams live indiagrams/.architecture-discovery.mdhas no further job once the spine exists — keeping it around just creates a second place that can go stale. Delete it. The spine and diagrams are now the only source of truth.correct-courseif reality contradicts a decision — don't regenerate the whole discovery file from scratch.Section-by-Section Checklist
Each row: what to resolve → expected answer shape → diagram needed?
Enum Legend — use these codes anywhere you reference a section (index tables, diagram filenames, notes,
correct-coursechange logs) instead of section numbers, since numbers shift if sections get reordered later.1. [ASP] Architecture Style & Principles
2. [SCD] System Context
3. [MBD] Module / Component Boundaries
Document (ingestion, storage) / Chat (conversation, retrieval) / Auth (identity, sessions).4. [DPR] Dependency Rules
X MUST NOT import Y/X MAY depend on Y, Z. E.g. "Domain must not import any framework or infrastructure package."project-context.mdverbatim so every future agent inherits it.5. [TLD] Technology & Library Decisions
pyproject.toml/package.json, not here — architecture states which technology, not the pinned version.6. [RFS] Repository / File Structure
src/domain/,src/application/,src/adapters/,src/infrastructure/, or your project's equivalent).7. [ADC] API / DTO Contract Strategy
openapi.yaml) if the project's complex enough to warrant one.8. [DTA] Data Architecture
erd-billing.mmd,erd-documents.mmd) rather than one mega-ERD nobody can read.9. [AEC] Async / Event Communication
10. [ASB] Auth & Security Boundaries
11. [ERH] Error Handling
12. [OBS] Observability
13. [UCP] Utility / Shared Code Placement
14. [TST] Testing Architecture
15. [DPA] Deployment Architecture
deployment-prod.mmd,deployment-staging.mmd) rather than one diagram with conditional notes scattered on it.16. [CDF] Critical Domain Flows
17. [SOT] Source-of-Truth Matrix
Exact dependency versions → pyproject.toml, not architecture doc.18. [GCH] Governance / Change Handling
correct-courseas the mechanism.Diagram Type Quick Reference
File Naming Convention
One rule underlies every split above: a diagram should answer exactly one question for exactly one reader. The moment you're adding a legend to explain "this part only applies in staging" or "this branch only happens on failure," that's the signal to split, not annotate.
Mermaid Examples Per Diagram Type
Copy-paste starting points. Each maps to a section above and its own file under
diagrams/.System Context —
diagrams/system-context.mmd(Section [SCD])
flowchart TB User([Freelancer User]) System[Invoice Reminder System] Stripe[(Stripe API)] Email[(Email Provider)] User -->|manages invoices| System System -->|charges / refunds| Stripe System -->|sends reminders| EmailComponent / Container —
diagrams/component-core.mmd(Section [MBD])
flowchart LR subgraph API Layer API[HTTP API] end subgraph Application App[Use Cases] end subgraph Domain Doc[Document Module] Chat[Chat Module] end subgraph Infrastructure DB[(PostgreSQL)] Queue[(Message Queue)] end API --> App App --> Doc App --> Chat Doc --> DB Chat --> QueueERD —
diagrams/erd-invoicing.mmd(Section [DTA])
erDiagram USER ||--o{ INVOICE : creates INVOICE ||--o{ REMINDER : triggers INVOICE { uuid id string client_name decimal amount date due_date string status } REMINDER { uuid id uuid invoice_id datetime sent_at string channel }Sequence —
diagrams/sequence-invoice-reminder.mmd(Section [AEC] / [CDF] — one file per flow)
sequenceDiagram participant Cron as Scheduler participant App as Reminder Service participant DB as Database participant Email as Email Provider Cron->>App: check overdue invoices (daily) App->>DB: query invoices where due_date < today DB-->>App: list of overdue invoices App->>Email: send reminder(invoice) Email-->>App: delivery confirmed App->>DB: mark reminder sentDeployment —
diagrams/deployment-prod.mmd(Section [DPA] — one file per environment)
flowchart TB Internet((Internet)) --> LB[Load Balancer] LB --> API1[API Container 1] LB --> API2[API Container 2] API1 --> DB[(PostgreSQL - Managed)] API2 --> DB API1 --> Redis[(Redis Cache)] API1 --> Queue[(Message Queue)] Queue --> Worker[Worker Container] Worker --> Email[(Email Provider)]Repository Structure —
diagrams/repo-structure.mmd(Section [RFS] — plain tree, not strictly mermaid, kept as a code block for readability)
Standing Instruction: Post-Approval Update Mode
Once a project's documents (spine, diagrams,
project-context.md) have been through initial approval, do not re-run the full discovery/verification workflow above for that project again. Instead:correct-course-style update: identify what changed → identify which sections/diagrams depend on it → update only those → leave everything else untouched.Diagram Generation & Approval Rules
These rules govern every diagram file from the moment it's first generated to the moment it becomes part of the implementation docs. They apply regardless of which BMAD skill (if any) is available on your install — they're workflow discipline, not tool-dependent.
Generate as
.mmdfiles. Every diagram is its own standalone Mermaid file, never embedded inline as a first draft. This keeps each diagram independently reviewable, editable, and versionable.Separate files by context, sized for easy review. One diagram = one question for one reader (per the split rules earlier in this doc). If a diagram needs a legend to explain "this part only applies in X," that's a signal it's crammed — split it into two files instead of adding an annotation.
Only one step in the sequence at a time. Diagrams are generated one at a time, in the order of the checklist sections above — not batch-generated. Each one is drafted, reviewed, and resolved before the next one starts. This keeps feedback isolated to a single decision instead of forcing you to review five diagrams' worth of assumptions at once.
Draft status until explicit approval. A newly generated
.mmdfile is not indexed and not part of the implementation docs the moment it's created. It stays in a draft/staging location (e.g.diagrams/_draft/) until you explicitly approve it. Nothing downstream — spine, stories, dev agents — should treat a draft diagram as authoritative.On approval: move, index, then advance. Once you approve a diagram:
diagrams/).Diagram Index (maintain this table in
ARCHITECTURE-SPINE.md)diagrams/system-context.mmddiagrams/component-<module>.mmddiagrams/erd-<context>.mmddiagrams/sequence-<flow>.mmddiagrams/deployment-<env>.mmdAccountability rule: each indexed diagram file is solely responsible for reflecting its own decision. If a decision changes, only that file (and its index row) needs updating — not the whole spine, not other diagrams. This is what makes targeted
correct-course-style updates possible instead of a full re-review.All reactions