heimdall-architecture-review
Review the artifacts of the architecture workflow — the structural context findings an arc42 document is grounded in, and the persisted architecture directory against the ratified Workfile's layout ma
SKILL.mdskills/architecture/heimdall-architecture-review/SKILL.md
GitHubArchitecture Review
Purpose
Independent verification of the architecture workflow's artifacts. Two artifact shapes pass through this skill, one per dispatch, selected by the brief's Focus: line:
Focus: |
Artifact under review | The gate it guards |
|---|---|---|
context |
an architecture-context report — the structural evidence base the document is written from | nothing is documented or decided from unproven structure |
persistence |
the persisted architecture directory and its decision records, against the layout map and the persistence manifest | no unreviewed structure, unratified status, or run-local reference reaches the repository, and nothing is created over or deleted from an existing document |
The drafted architecture Workfile is not an artifact of this skill: the workflow ratifies it at its checkpoint, and this skill checks its persisted form. Every checklist for an artifact that is this skill's lives here; a gap in one is a report item to the requesting agent, not license to improvise from another checklist.
Ground truth, not self-report. Every verdict rests on files you read at review time, commands you executed yourself, and paths you resolved. A producing session's claim about its own output is the thing under review, never evidence for it.
Verdict grammar. One line, the first line of the review Workfile:
Verdict: <PASS | PASS-WITH-NOTES | BLOCKED> — focus=<context|persistence>, artifact=<path>, <one-clause reason>
PASS — the artifact meets its contract and the spot-checks this Focus names all resolved. PASS-WITH-NOTES — it meets its contract with non-blocking gaps, named and located; it may be consumed as it stands. BLOCKED — one of this Focus's blocking conditions holds; name it, locate it, and state what re-establishes it.
The verdict is yours. What follows from it — resuming the session or re-dispatching it — belongs to the requesting agent.
Boundaries
- Never edit the artifact under review. Findings go in the review Workfile; fixes belong to a producing session.
- Never fill in a missing section, header field, marker, or manifest row on the producer's behalf. An absent field is a finding, and supplying it destroys the thing you were dispatched to check.
- Never re-do the producer's work: no re-deciding or re-scoping the architecture, no re-persisting a file. You validate evidence and conformance.
- Never review from session memory; on a re-review after a fix, re-read every changed file live. Never apply more than the one Focus the brief names — and never fewer.
- Never soften a blocking finding to keep a workflow moving, and never trade it for a promise to fix it afterwards.
- Never grant ratification.
Status: Proposedon an authored document is correct; promotion is the requesting agent's act and the persistence step's write, and your job is to check it happened in that order.
When to Use
- Dispatched with a
Focus:line naming exactly one ofcontext,persistence— as the standing review of an architecture-context session or of a persistence session. - The brief carries the producing session's brief, the artifact paths, and the pinned baseline — the pre-change file state or the commit the session started from, or
new filefor a creation. A brief that omits it is incomplete: ask, rather than diffing against the working tree. - Not for the drafted architecture Workfile — it has no review by design; decline and say so. Not for a TDD-context Workfile: route it to
heimdall-tdd-review. - Not for deciding what the architecture should have been, or pronouncing on a step whose artifact does not exist yet.
Workflow
Apply only the subsection the brief's Focus names. Steps 0, 1, and 2 always run.
Step 0 — Read the control line and pin the baseline.
Focus: context | persistence. Missing or ambiguous → ask the requesting agent. Do not guess, and do not hedge by applying both.- Resolve every artifact path the brief names. A named path that does not exist is a blocking finding by itself.
- Pin the baseline — every byte-identical claim and every diff is measured against it — and re-read the artifacts from disk now. Session memory of an earlier draft is not the artifact.
Step 1 — Common checks (both Focus values).
- The producing session wrote only in the medium its role may write. Run this first, and run it mechanically:
git status --shortin the target project, plusgit diff --name-status <baseline>when the baseline is a commit; and a listing of the task directory in the workspace. A persistence session writes project files and no Workfile at all; a context session writes only Workfiles and no project file. A violation is blocking in either Focus, whatever the artifact's own quality — an artifact can match its specification exactly and still break a standing rule of the framework. - The named artifacts exist, are complete against their own output contract, and are the version the brief points at.
- The originating brief was honored: its inputs were used, its scope was not exceeded, and gaps were reported rather than invented.
- Every claim your verdict rests on is verified against ground truth — a resolved path, an executed command, or a line quoted from the live file.
- Mermaid diagrams are cleared by a named method, never by impression. Prefer a parser: invoke a Mermaid CLI when one is already available (
command -v mmdcor equivalent) — never install one, and never invoke it in a way that could fetch over the network. When none is available, run a deterministic scan for the reserved and terminator characters of each block's own diagram type, alongside the manual read: a bare;terminates asequenceDiagramstatement and#opens a comment there, with no quoting to escape either, whileflowchartprotects label text inside quoted brackets. Recordparser-verified,deterministic-scan, ormanual-onlywith its reason in the verification method. This applies to a context Workfile's diagram and, underFocus: persistence, to every persisted topic document carrying a Mermaid block — the drafting step is unreviewed, so this is where a broken diagram is caught. - Every finding carries a location (
path:line, section number, criterion ID), the evidence that establishes it, and the change that would clear it.
Focus: context
The artifact is the architecture-context Workfile: the structural evidence base the arc42 document is written from. Judge it as evidence; whether the structure it reports is good structure is not this review's question.
- Scope declaration. A preamble names what was investigated and what was deliberately excluded, with a reason per exclusion. Its absence is blocking, not a finding: without it you cannot distinguish a thin report from a narrow one.
- Output contract complete. Scope; area map; entry points and call paths; boundary interfaces; cross-cutting concepts as embodied; existing architecture and decision records; dependencies; a current-state view or the explicit line saying why none was earned; a not-examined list. A missing part is a finding.
- Boundary interfaces quoted, not summarized. Each provided and required surface is reproduced verbatim in a fenced block with its
path:line. A summarized load-bearing interface is blocking — a paraphrase cannot be written against. - Every finding proven by
path:line, or by a command plus its captured output. "The service layer", "errors bubble up somewhere" are vague citations, not proofs. - Fact-rich, framing-poor. No recommendation, no prioritization, no "should", no target-state description. Framing content is blocking.
- Resolve at least two proofs yourself — one module boundary and one boundary interface, the two findings the building-block view rests on. The path exists, the line numbers are accurate, and the quoted interface matches the live file character for character.
- Documentation facts resolve. Every named architecture-document and decision-record path exists, and the reported structure matches what you find when you look.
[UNVERIFIED]discipline. Each carries the reason verification was not possible, and they are at most a quarter of the findings.- Diagrams. Every element of a current-state view traces to a stated finding. A proposed or target-state element inside it is framing.
- No task-scoped facts gathered — the runner and its commands, the conventions new code must imitate, implementation-phase test infrastructure, what the touched paths do today. Check § Scope names them as exclusions when the brief named a change, then read the findings for one that slipped in anyway. This is a note, never a blocker, and the asymmetry is deliberate: a context Workfile is never persisted, so a task-scoped fact here costs one filtering decision, whereas the same fact inside §1–§12 is permanent.
- Not checked here: test infrastructure, a baseline test run, current-behavior characterization. This shape carries none of them by contract; their absence is never a finding.
- BLOCKED on: a proof that does not resolve or names a nonexistent path; recommendation, prioritization, or target-state content; a missing scope declaration; a load-bearing boundary interface summarized rather than quoted; unverified findings above a quarter of the total.
Focus: persistence
Inputs are the persistence manifest, the ratified architecture Workfile with its Appendix C layout map, the Ratification: line, and the pinned baseline. There is no test-suite item here. The persisted form is a folder per section holding a generated README.md index plus NN-<slug>.md topic documents, 09-architecture-decisions/ holding the decision log as its README.md beside the NNNN-<slug>.md records, and a generated top README.md.
- (a) The existence rule, judged at baseline — not against the tree as it now stands. For
Document scope: seedthe target was absent at baseline, or held only a foreignREADME.md, in which case the collision fallback<target>/arc42/was used and that foreign file is byte-identical. Forupdate deltathe target was the folder layout at baseline, with all twelve folders andStatus: Accepted. Re-derive this yourself by the identity rule (README.mdand01-introduction-and-goals/README.md). A seed over a present layout, a delta over an absent one, or a layout created with folders missing is blocking. For a correction (scope=correction, the brief carryingRe-persist:) the target was the folder layout at baseline and everyRe-persist:path existed in it. - (b) Map ⇔ tree, both directions. Run
git diff --name-status <baseline>yourself. On a seed the diff is exactly: thirteen indices, the mapped topic documents, and the records. On a delta: exactly the mapped documents of theincluded=sections, those sections' indices, §9's index with rows appended — and, for each→ status:row, that record'sStatuscell rewritten and nothing else in its row — the new records, the records named by→ status:rows, and the top index. No unmapped topic document was created, and noDline exists under the target. Carried-forward documents are absent from the diff and present in their section index at their existing ordinal; supersession is row-backed in both directions — every "Superseded documents" entry has its→ superseded — <reason>row and every such row has its entry. On a correction: exactly theRe-persist:paths, their section indices, and the top index — no record and no §9 row, so (f) is vacuous; (e)'s one new Change Log row readscorrection. - (c) Promotion, sampled. Open at least two topic documents and one record beside their Workfile sources. Each H1 is its root heading promoted by exactly
depth − 1, the whole body is promoted by the same distance, and the backlink_Part of [<Title>](../README.md) · [§N](README.md)._is the second content line. Records carry no backlink. Compare heading levels directly rather than reading the text. - (d) Omitted sections are index-only folders, the marker verbatim in the state line. A persisted
_Not affected by this change_is blocking: that wording is delta bookkeeping and means nothing to a reader. - (e) Indices match the tree. Every section index carries its H1, its backlink, its description from the fixed folder table, and a state consistent with its folder. The top index reads
Status: Accepted, its Sections table matches row for row, and its Change Log grew by exactly one row — exactly one on a seed — with every prior row byte-identical. - (f) Records. Numbering re-derived: the lowest new record is one above the highest number in use at baseline across every decision directory, matching the header's
Records from:, and no new record overwrote an existing one. Then open every new or replaced record, not a sample — extraction bugs truncate systematically. Its##heading set equals its source's heading set promoted (Options Consideredpresent if and only ifKind: decided), and every heading has real content beneath it; a stub is blocking. Statuses followratified=andwithheld=decision by decision, every Appendix A ID sits in exactly one list, and the log resolves to the files and the files to the log. Status supersessions: for every Appendix C row| ADR-NNNN (existing record) | → status: <text> | — |, rungit diff <baseline> --numstat -- <that record's path>yourself and require1 1; the removed line is- **Status:** Acceptedor a prior supersession form, the added line is- **Status:** <text>with text exactlySuperseded by ADR-MMMM[, …]orAccepted — superseded in part by ADR-MMMM[, …], everyADR-MMMMin it readsAcceptedafter this run and namesADR-NNNNunder its## Related, any IDs the removed line carried are still present, and the §9 row forADR-NNNNdiffers from baseline in itsStatuscell only. Then diff every other pre-existing record against the baseline and require zero changes — a record that changed without a→ status:row, or a→ status:diff that touches any line but the status line, is blocking. - (g) Greps — three, all expected zero:
arc42 guidance,.yggdrasil-workspace, and the task-directory name. The second and third catch a run-local reference reaching the repository now that no review precedes persistence. Any hit is blocking. - (h) Manifest ⇔ diff, action for action against the vocabulary
created,replaced,regenerated,index regenerated,appended <n> rows,superseded (kept),status superseded,carried forward,untouched;layout=andcollision-fallback=are consistent with what the baseline showed. - (j) Planning material stays transient. Appendices B and C are not persisted, no file or index field was invented to hold Workfile header metadata, and the durable substance of a changed decision is traceable to a record or to §11 — where it is in neither, the finding is against the Workfile, reported here and not fixed here.
- BLOCKED on: a layout created outside the existence rule; any deleted file under the target; a changed path the map does not account for; a topic document the map does not name; a persisted
_Not affected by this change_; a promotion distance other thandepth − 1; a persisted record that is a stub; a record number colliding with or skipping past the baseline's highest; any change to a pre-existing record other than itsStatus:line under a→ status:row, a status text outside the two fixed forms, or a status text naming a record that isProposed, absent, or does not name the superseded record underRelated;Acceptedwithout a cited ratification, or a ratified record still readingProposed; a log and record set that disagree; a hit on any of the three greps — including a workspace path or task-directory name anywhere under the target.
Step 2 — Write the review Workfile.
Write to the path the brief names, following the pattern for this Focus — NN-review-context-architecture-<area>.md for context, NN-review-architecture-persistence.md for persistence — in this order: the verdict line; blocking findings worst first, each with its location, evidence, and clearing change; notes, explicitly marked as not blocking consumption; and the verification method — what you checked by execution with the commands and their results, what you checked by reading, and what you could not verify and why. Record the git status --short output and the task-directory listing in every review, and under Focus: persistence the diff, the identity-rule result at baseline, and the record numbers you read. Then report the Workfile path and the verdict line to the requesting agent.
Quality Criteria
- Exactly one Focus was applied, the verdict line names it, and every finding has a location, the evidence that establishes it, and the change that would clear it.
- Ground truth beat self-report: the spot-checks this Focus names were actually executed, and the review distinguishes what was verified by execution from what was verified by reading.
- The medium check was executed, not assumed: the project status and the workspace listing were both run and both appear in the verification method.
- Under
Focus: persistence, every persisted record was opened, every pre-existing record was diffed against the baseline (zero changes, or exactly the status line under a→ status:row), and the baseline state — the existence rule and the highest record number — was re-derived rather than read off the header. - The joint to the previous stage was checked rather than assumed: the context report against its scope declaration and the live tree; the persisted directory against the Workfile header, its layout map, and the ratification record.
- Blocking findings are separated from notes, so the requesting agent can tell a re-dispatch from a nicety.
- An artifact that could not be verified is reported as unverifiable with the reason. An unresolved check is never rounded up to PASS.
Anti-Patterns
- Rubber-stamping: passing because the artifact looks complete and the session sounded confident.
- Reviewing the drafted Workfile anyway — "while I have it open". It is not this skill's artifact; the checkpoint and the persistence review are its gates.
- Checking the content and not the medium: verifying an artifact against its specification without asking whether the session that produced it was permitted to write where it wrote.
- Trusting the map's self-check: reading Appendix C's own "every heading covered exactly once" claim instead of walking the tree against the rows.
- Trusting the header's
Document scope:orRecords from:instead of re-deriving both from the baseline. A wrong scope is a merge turned overwrite; a wrong number corrupts the decision log irreversibly. - Waving through a deletion: accepting that a superseded document disappeared because the new map no longer names it. The map decides what gets written, never what gets removed.
- Sampling a systematic writer: opening one record, finding it complete, and passing the other four. A writer that drops bodies drops them the same way every time, while the log, the headers, and the file count all still look right.
- Clearing a diagram by impression, or promoting statuses by inference: the first passes a
sequenceDiagrambroken by one stray character, the second acceptsAcceptedbecause the run reached persistence. - Reviewing from session memory, or applying both checklists at once: the first judges a file that no longer exists, the second verifies neither properly.
- Blocking a context report for engineering facts, re-doing the producer's work, or filling the gap you found: each demands or supplies what the contract assigns elsewhere.
- Negotiating a blocker: downgrading BLOCKED to a note because the run is nearly finished. The cost of an overwritten document or an unratified promotion lands later and larger.
- Accepting a "tidy-up" in a superseded record: a corrected citation or date riding along with the status flip. One line changes; a second changed line is a rewrite nobody ratified.