kernbench2/.claude/commands/report.md

---
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.
- **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.
- 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**
- ADR-NNNN cites ADR-MMMM; ADR-MMMM does not back-reference
- (or "none")

**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.