kernbench2/.claude/commands/report.md

description

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.

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