ywkang
1f36baa898
Fill component-model coverage gaps surfaced by /report's G4 analysis. Each ADR documents the component's First action, latency model, and honest notes on dormant code or implementation asymmetries discovered during re-evaluation against current code. - 0038 pcie_ep: thin protocol-overhead model; ComponentBase forwarding worker as-is; named-node contract for router helpers - 0039 pe_mmu: component + utility dual role; sub-page region stopgap; D2.1 flags pipeline path missing mmu.overhead_ns timeout (asymmetric with non-pipeline; not visible at default tlb_overhead_ns=0) - 0040 pe_tcm: dual-channel BW serialization (read/write Resource cap=1); TcmRequest schema owned by TCM; timing-only (no data store) - 0041 sram: terminal scratchpad model + ResponseMsg on reverse path; D1.1 flags _worker override as currently dormant (no Transaction actually targets the SRAM node today) - 0042 tiling: pure plan-generator module, not a component; corrects the G4 misclassification; pins GEMM/Math stage sequences and epilogue scope contract Also: /report skill G3 refinement — only flag older->newer asymmetric cross-references; newer->older (e.g., 0034-0037 citing infrastructure ADRs) are expected one-way and no longer reported. Bilingual pair verifier (tools/verify_adr_lang_pairs.py) passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
328 lines
13 KiB
Markdown
328 lines
13 KiB
Markdown
---
|
||
description: Generate a public-facing architecture design document from approved ADRs and SPEC.md, with gap analysis reported to chat only.
|
||
---
|
||
|
||
# `/report` — Architecture Design Document Generator
|
||
|
||
Generates a **public-facing** architecture design document at
|
||
`docs/report/architecture-{YYYY}-{1H|2H}.md` derived from the current ADR
|
||
corpus, SPEC.md, CLAUDE.md, and the canonical component list.
|
||
|
||
This command is **strictly read-only** on `docs/adr/`, `SPEC.md`,
|
||
`CLAUDE.md`, and `src/`. The only write is the report file itself
|
||
(a derived artifact under `docs/report/`).
|
||
|
||
---
|
||
|
||
## Invocation
|
||
|
||
Two modes:
|
||
|
||
- `/report` — **dry-run** (default). No file is written. The command
|
||
reads sources, performs classification, and reports the planned TOC
|
||
+ gap analysis to chat only. Use this to validate ADR-to-section
|
||
mapping before committing.
|
||
- `/report write` — **write mode**. Performs the same procedure and
|
||
writes `docs/report/architecture-{period}.md`. Use after a dry-run
|
||
whose classification looks correct.
|
||
|
||
Period determination (both modes), from system date:
|
||
|
||
- month 1–6 → `{YYYY}-1H`
|
||
- month 7–12 → `{YYYY}-2H`
|
||
|
||
In write mode, if `docs/report/architecture-{period}.md` already exists,
|
||
overwrite it without asking (regeneration is the expected operation).
|
||
|
||
---
|
||
|
||
## Output Contract
|
||
|
||
### Document body (`docs/report/architecture-{period}.md`)
|
||
|
||
Public release form. Reader is an external developer/architect. They do
|
||
**not** have access to SPEC.md or ADR files. Therefore:
|
||
|
||
- **No `ADR-NNNN` identifiers** in visible prose.
|
||
- **No `SPEC R/§` identifiers** in visible prose.
|
||
- **No internal jargon** assumed without definition.
|
||
- **No diagram embeds** — only `<!-- DIAGRAM: ... -->` placeholders.
|
||
- **Attribution via HTML comments** — every prose paragraph that derives
|
||
from a source carries an inline comment immediately above it:
|
||
`<!-- src: ADR-NNNN <section-name> -->` (multiple sources allowed).
|
||
|
||
### Chat-only report (not written to any file)
|
||
|
||
After writing the document, report to the user in the chat response:
|
||
|
||
- File path written.
|
||
- Section counts (e.g., "Detailed Architecture: 8 components covered,
|
||
2 in `builtin/` have no ADR backing").
|
||
- **G1 gaps** — SPEC requirements (R-numbers / §) with no ADR citing them.
|
||
- **G2 gaps** — ADRs missing **Context** or **Decision**. Alternatives
|
||
and Consequences are optional; their absence is NOT a gap.
|
||
- **G3 gaps** — ADR cross-references without a back-reference.
|
||
Only flag when the referencer's ADR number is **less than** the
|
||
referenced ADR's number (older → newer). Newer ADRs citing older
|
||
infrastructure ADRs (higher number → lower number) are expected to
|
||
be one-way and are NOT flagged.
|
||
- **G4 suggestions** — areas where an ADR seems missing based on the
|
||
ADR corpus + SPEC reading. Phrase as suggestions, not findings. Each
|
||
G4 item must say *why* it's suggested and remain falsifiable.
|
||
- **G5 consistency issues** — ADR-to-ADR inconsistencies:
|
||
- **G5a (supersession not reflected)** — ADR-A states it supersedes
|
||
ADR-B, but ADR-B's Status is not marked as Superseded.
|
||
- **G5b (merge candidates)** — two or more ADRs cover near-identical
|
||
scope (detected naturally during section assignment, not via
|
||
exhaustive pair-wise scan).
|
||
- **G5c (explicit contradictions)** — two ADRs whose Decisions
|
||
directly oppose each other. Must cite both quotations; do not
|
||
speculate contradictions from topical similarity alone.
|
||
- **TOC rationale** — for each section, list contributing ADR IDs
|
||
(this is for the user's verification only, never written to the
|
||
document itself).
|
||
|
||
G4 must never appear in the document body. G1–G3 are also chat-only.
|
||
|
||
---
|
||
|
||
## Procedure
|
||
|
||
### Step 1 — Determine period
|
||
|
||
Use current system date. Compute `{YYYY}-1H` or `{YYYY}-2H`.
|
||
|
||
### Step 2 — Ingest ADRs
|
||
|
||
For each `docs/adr/ADR-NNNN-*.md`:
|
||
|
||
- If both `ADR-NNNN-*.md` (Korean) and `ADR-NNNN-*.en.md` (English)
|
||
exist for the same number, **prefer the Korean `.md`** version.
|
||
- Parse for the four canonical sections: Context, Decision, Alternatives
|
||
(also accept "Alternatives Considered"), Consequences.
|
||
- Record presence/absence of **Context** and **Decision** for G2.
|
||
Alternatives and Consequences presence is recorded for use during
|
||
authoring, but their absence is not a gap.
|
||
- Record ADR-NNNN cross-references for G3, preserving the direction
|
||
(referencer → referenced). G3 evaluation uses ADR numbers to
|
||
distinguish older→newer (flagged when missing back-link) from
|
||
newer→older (not flagged; see *Output Contract* G3).
|
||
- Record Status (e.g., Accepted, Superseded, Draft) and any "supersedes
|
||
ADR-NNNN" text in the body for G5a.
|
||
|
||
Process ADRs in **numerical order** for determinism.
|
||
|
||
### Step 3 — Read canonical component list
|
||
|
||
List `src/kernbench/components/builtin/*.py`, excluding `__init__.py`,
|
||
`pe_types.py`, and `__pycache__/`. Sort alphabetically. This is the
|
||
canonical order for Detailed Architecture subsections.
|
||
|
||
### Step 4 — Read SPEC.md and CLAUDE.md
|
||
|
||
For G1 detection: extract every `R<N>` and `§<X.Y>` identifier mentioned
|
||
in SPEC.md. For each ADR, check which of these it cites. SPEC IDs with
|
||
zero citing ADRs → G1.
|
||
|
||
### Step 5 — Section assignment
|
||
|
||
Assign each ADR to exactly one of:
|
||
|
||
- **Design Principles** — project-wide rationale, philosophy, mission
|
||
(e.g., "why source-level kernel execution", "why fast multi-device
|
||
scaling"). Includes ADRs that describe foundational invariants
|
||
(e.g., latency model assumptions, verification strategy).
|
||
- **High-level Architecture** — Tray / SIP / CUBE / PE hierarchy and
|
||
cross-layer boundaries (e.g., runtime API ↔ sim_engine ↔ components).
|
||
- **Detailed Architecture** — single-component internal designs. One
|
||
subsection per file in the canonical component list. ADRs whose
|
||
primary topic is the internal structure of one component go here.
|
||
- **Implementation Decisions** — **cross-cutting** algorithms / policies
|
||
/ schemes / models that don't belong to a single component:
|
||
collective algorithms, parallelization policies, address schemes,
|
||
routing algorithms, model assumptions.
|
||
|
||
Boundary rule between Detailed Architecture and Implementation Decisions:
|
||
|
||
> Detailed Architecture = component-internal.
|
||
> Implementation Decisions = spans multiple components OR is an
|
||
> algorithm/policy/scheme/assumption rather than a structural choice.
|
||
|
||
If an ADR fits two sections plausibly, prefer the one that minimizes
|
||
duplication and pick the more specific bucket (Detailed if it primarily
|
||
concerns one component, else Implementation Decisions).
|
||
|
||
During classification, opportunistically detect ADR consistency issues:
|
||
|
||
- **G5b (merge candidate)** — if two or more ADRs land in the same
|
||
Detailed Architecture subsection or the same Implementation Decisions
|
||
topic AND their primary scope is near-identical, record as a merge
|
||
candidate. Topical adjacency is not enough; the scopes must be
|
||
effectively the same question.
|
||
- **G5c (explicit contradiction)** — if while reading you encounter two
|
||
ADRs whose Decisions directly oppose each other on the same question,
|
||
record both quotations verbatim with their ADR IDs. Do NOT speculate
|
||
contradictions from similarity, vocabulary, or domain overlap — only
|
||
explicit, citable opposition.
|
||
|
||
Do NOT perform an exhaustive pair-wise scan of all ADRs. G5b/G5c are
|
||
byproducts of normal reading; if not encountered, the chat report
|
||
shows "(none)".
|
||
|
||
### Step 6 — Write the document (write mode only)
|
||
|
||
In **dry-run mode**, skip this step entirely. Proceed directly to Step 7.
|
||
|
||
```markdown
|
||
# KernBench — Architecture Design Document
|
||
*{YYYY} {1H|2H}*
|
||
|
||
## Design Principles
|
||
<prose>
|
||
|
||
## High-level Architecture
|
||
<intro prose>
|
||
|
||
### Tray
|
||
### SIP
|
||
### CUBE
|
||
### PE
|
||
|
||
## Detailed Architecture
|
||
### <component-1>
|
||
### <component-2>
|
||
...
|
||
|
||
## Implementation Decisions
|
||
### <topic-1>
|
||
### <topic-2>
|
||
...
|
||
```
|
||
|
||
#### Authoring rules (apply to every section)
|
||
|
||
- **Stay grounded.** Every claim must trace to an ADR's stated content
|
||
(Context / Decision / Alternatives / Consequences). No invented
|
||
motivation, no invented alternatives, no invented trade-offs.
|
||
- **4-part discipline, naturally.** Each subsection should naturally
|
||
cover: the problem the design addresses, the decision made, the
|
||
alternatives considered, the consequences. Do **not** label these
|
||
with rigid headers like "**Problem.**" — weave them into prose. But
|
||
ensure all four are present *if the source ADR documents them*.
|
||
- **Missing → omit, not fabricate.** If a source ADR has no
|
||
"Alternatives" section, do **not** invent alternatives for the
|
||
report. Simply write the remaining parts and record G2 in chat.
|
||
- **Attribution.** Every paragraph derived from one or more ADRs
|
||
carries an HTML comment immediately above:
|
||
`<!-- src: ADR-NNNN <section> [, ADR-MMMM <section>] -->`.
|
||
- **Diagram placeholders.** Where a diagram would help, insert
|
||
`<!-- DIAGRAM: <short description of what the diagram should show> -->`
|
||
on its own line. **Never** embed an image (``).
|
||
- **Public tone.** Self-contained. Define internal terms (SIP, CUBE,
|
||
PE, Tray, NOC, IPCQ, TCM, etc.) on first use within the document.
|
||
Do not assume reader has read SPEC or ADRs.
|
||
- **No internal references.** No `ADR-NNNN` in body text. No
|
||
`SPEC §X.Y` or `R<N>` in body text. These appear only inside HTML
|
||
attribution comments.
|
||
- **Detailed Architecture component subsections.** Use the canonical
|
||
list from Step 3 in order. For each component file, write a
|
||
subsection drawing from any ADR that primarily concerns that
|
||
component. If no ADR covers a component, write a one-line stub
|
||
noting the component exists and flag it in chat report. If an ADR
|
||
covers a topic not in the canonical list, place it under
|
||
"Detailed Architecture → Other" (sub-subsection) and flag for
|
||
canonical-list extension in chat.
|
||
- **Implementation Decisions topic naming.** Derive topic names from
|
||
ADR titles, made reader-friendly (no ADR number). Group related
|
||
ADRs under one topic when natural (e.g., multiple address-related
|
||
ADRs under "Address Scheme").
|
||
|
||
### Step 7 — Generate chat report
|
||
|
||
After Step 6 (write mode) or directly from Step 5 (dry-run mode),
|
||
emit the following to chat. Do **not** write any of this to a file.
|
||
|
||
In **dry-run mode**, replace the `Wrote:` line with:
|
||
`**DRY-RUN — no file written.** Review TOC and gaps below. Run \`/report write\` to commit.`
|
||
|
||
```
|
||
## /report — Generation Summary
|
||
|
||
**Wrote:** docs/report/architecture-{period}.md
|
||
|
||
**Section coverage**
|
||
- Design Principles: <N> ADRs
|
||
- High-level Architecture: <N> ADRs
|
||
- Detailed Architecture: <covered>/<total> components ; components without ADR: [...]
|
||
- Implementation Decisions: <N> topics, <N> ADRs
|
||
|
||
**TOC rationale (ADR → section mapping)**
|
||
- Design Principles: ADR-NNNN, ADR-MMMM
|
||
- High-level Architecture: ...
|
||
- Detailed Architecture → <component>: ADR-NNNN
|
||
- Implementation Decisions → <topic>: ADR-NNNN, ADR-MMMM
|
||
|
||
**G1 — SPEC requirements without ADR support**
|
||
- R<N> / §<X.Y>: not cited by any ADR
|
||
- (or "none")
|
||
|
||
**G2 — ADRs missing required sections (Context or Decision)**
|
||
- ADR-NNNN: missing <Context|Decision>
|
||
- (or "none")
|
||
|
||
**G3 — Broken cross-references** (older → newer only)
|
||
- ADR-NNNN cites ADR-MMMM (NNNN < MMMM); ADR-MMMM does not back-reference
|
||
- (or "none")
|
||
- Note: newer ADRs citing older infrastructure ADRs (NNNN > MMMM) are
|
||
not flagged here — one-way references are the expected pattern.
|
||
|
||
**G4 — Suggested topics that may warrant a new ADR (verify before acting)**
|
||
- <topic>: <why agent thinks it may be missing — must be falsifiable>
|
||
- (or "none")
|
||
|
||
**G5 — ADR consistency issues**
|
||
- **G5a (supersession not reflected)**
|
||
- ADR-NNNN claims to supersede ADR-MMMM, but ADR-MMMM Status is "<status>"
|
||
- (or "none")
|
||
- **G5b (merge candidates)**
|
||
- ADR-NNNN + ADR-MMMM: near-identical scope on <topic> — evaluate merge
|
||
- (or "none")
|
||
- **G5c (explicit contradictions)**
|
||
- ADR-NNNN says "<quote>"; ADR-MMMM says "<quote>" — direct opposition on <question>
|
||
- (or "none")
|
||
```
|
||
|
||
---
|
||
|
||
## Constraints (do not violate)
|
||
|
||
1. **Read-only on source.** No writes to `docs/adr/`, `SPEC.md`,
|
||
`CLAUDE.md`, or `src/`. Only write is
|
||
`docs/report/architecture-{period}.md`.
|
||
2. **No fabrication.** Every body paragraph traces to ADR content via
|
||
HTML attribution comment.
|
||
3. **No diagram embeds.** Placeholders only.
|
||
4. **No internal IDs in body.** ADR-NNNN and SPEC R/§ stay inside
|
||
HTML comments only.
|
||
5. **Determinism.** ADRs processed in numerical order; components in
|
||
canonical (alphabetical) order. Same inputs → same output.
|
||
6. **G4 stays in chat.** Never written to the document.
|
||
7. **Korean bilingual preference.** When both `.md` and `.en.md`
|
||
exist for the same ADR number, use `.md`.
|
||
8. **All ADRs included.** No exclusion list. ADRs about internal
|
||
tooling (CLI, diagram views, verification strategy) are still
|
||
included — usually under Design Principles or Implementation
|
||
Decisions, written in publishable form.
|
||
|
||
---
|
||
|
||
## Failure modes to avoid
|
||
|
||
- **Padding** with general background not present in the source ADRs.
|
||
- **Inferring alternatives** the ADR doesn't mention.
|
||
- **Quietly skipping** an ADR because it seems internal. Include it,
|
||
rephrase for public audience.
|
||
- **Inventing components** not in `src/kernbench/components/builtin/`.
|
||
- **Auto-selecting diagrams** from `docs/diagrams/`. Only placeholders.
|
||
- **Promoting G4 suggestions to the document.** They stay in chat.
|