structure

Files (2)

• SKILL.md
• owns-defers.md

SKILL.md (first lines)

# Structure (QRSPI Step 6)

**PRECONDITION:** Invoke `qrspi:using-qrspi` skill to ensure global pipeline rules are in context. (Idempotent on session re-entry. Subagents are exempt — SUBAGENT-STOP in using-qrspi handles that.)

**Announce at start:** "I'm using the QRSPI Structure skill to map the design to files and interfaces."

## Overview

Map the design's vertical slices to specific files, components, and interfaces. Define what gets created vs modified, show how slices map to the stack, and produce a detailed architectural diagram. This is the bridge between abstract design and concrete implementation.

Structure authors: the unified system architecture diagram(s) for the release (Mermaid or equivalent — stitching the components named across design.md's per-solution and cross-cutting-CD blocks into a single architectural overview); file maps and module-boundary contracts; cross-solution component interactions; unified test architecture (the `## Test Architecture` section in structure.md); and per-type stitching of per-solution acceptance criteria from design.md.

<!-- Soft length target: 300–500 lines for this SKILL.md. The marker is a guidance signal — long enough to carry per-section template guidance + worked examples + iron laws, short enough to keep the prompt scannable in a single context window. -->

## Structure OWNS / Structure DEFERS

!cat skills/structure/owns-defers.md

## Artifact Gating

**Required inputs:**
- `goals.md` with `status: approved`
- `research/summary.md` with `status: approved`
- `design.md` with `status: approved`
- `phasing.md` with `status: approved`

If any artifact is missing or not approved, refuse to run and tell the user which artifact is needed.

Read `config.md` from the artifact directory to determine whether Codex reviews are enabled.

### Config Validation

Apply the **Config Validation Procedure** in `using-qrspi/SKILL.md`. Structure validates `second_reviewer`.

<HARD-GATE>
Do NOT produce structure.md without approved goals.md, research/summary.md, design.md, AND phasing.md.
Do NOT proceed to Plan without user approval of the structure.
</HARD-GATE>

## Execution Model

**Subagent per round** (iterative with human feedback). Each round is a fresh subagent with declared inputs + any feedback from prior rounds.

## Phase-Scoped Content Rules (consumer guidance)

> **Consumer guidance, not authoritative source.** The authoritative source for phasing decisions, vertical slice authoring, roadmap maintenance, and current-phase scoping is the **Phasing** skill (`skills/phasing/SKILL.md`). Structure consumes phasing decisions from `phasing.md` (and pruned `design.md`); it does not own them. The text below restates the consumer-side expectations Structure honors when reading those upstream artifacts.

When generating `structure.md`, Structure honors the phase scope set by Phasing: structure.md reflects ONLY current-phase file maps and interfaces (per `phasing.md` + the pruned `design.md`). Entries are tagged with goal IDs. File maps for goals not in the current phase (per `roadmap.md`, which Phasing authors) do not appear in `structure.md`. Structure verifies every goal ID in the file map exists in the current-phase `goals.md`; cross-phase scoping decisions and any change to the phase boundary itself are Phasing's responsibility — Structure refers the user back to Phasing if a scope shift is needed rather than re-authoring the phase split.

## Multi-Actor Flow Check

!cat skills/_shared/multi-actor-flow-check.md

## Process

### Structure Subagent

**Inputs:**
- `goals.md`
- `research/summary.md`
- `design.md`
- `phasing.md` (current-phase scope source — Phasing-owned)
- Any prior feedback files

**Task:** Map the design to concrete files and interfaces.

1. Map each vertical slice from `design.md` to specific files and components
2. For each slice, show which layers of the stack it touches and what files are involved
3. Define interfaces between components (function/class signatures, not implementations)
4. Identify create vs modify for each file
5. Detailed Mermaid architectural diagram: file/module layout, API endpoints, data flow, interface boundaries
6. If CI setup noted in Design, define pipeline structure (workflow file, test commands, lint config) and project convention files (CLAUDE.md, linting config, etc.) for greenfield projects

**Output format for `structure.md`:**

!cat skills/_shared/evergreen-output-rule.md

> **Per-section template guidance is embedded inline as HTML comments below.** Each section block carries a one-line guidance comment and a conformance reminder so future structure.md content can be linted for boundary-drift signals (the scope-reviewer's boundary-drift sub-check looks for skill-implementation jargon — specific tool names, hook syntax, subagent dispatch verbs — leaking into earlier-stage artifacts; structure.md owns file paths and interfaces, not Plan/Implement-layer language).
>
> **Conformance applies to every section of structure.md.** Claim-before-evidence (lead each subsection with its decision sentence; supporting detail follows). Paragraph density: ≤150 words / ≤8 lines per paragraph; if longer, split. Scannability: bullets in any section longer than ~12 lines. Required-section heading match: the headings below (`## File Map`, `## Interfaces`, `## Architectural Diagram`, `## CI Pipeline`) are the canonical set; do not silently rename. No-brevity prohibition: do NOT add "be concise", "brief summary", "≤ N lines" framing; the soft length target is set in this SKILL.md, not in the artifact.

````markdown
---
status: draft
---

# Structure: {Project/Feature Name}

<!-- Lead with one claim sentence describing the project scope; do NOT restate Design's architecture. -->

## File Map

<!-- Per-section guidance: one row per file. Action ∈ {Create, Modify}. Responsibility is a one-line behavior summary at the boundary level — NOT line-by-line logic, NOT LOC estimates, NOT commit ranges (those belong to Plan). Bullets/tables for scannability; concrete paths only — no directory placeholders. -->

### Slice 1: {name}
| File | Action | Responsibility | Goal IDs |
|------|--------|---------------|----------|
| `path/to/file.ts` | Create | {what it does at the boundary} | {G1, G2} |
| `path/to/existing.ts` | Modify | {what changes at the boundary} | {G1} |

### Slice 2: {name}
...

## Interfaces

<!-- Per-section guidance: explicit signatures with concrete types. NO `any`, NO `object`, NO `TBD`. Plan reads these to define task boundaries. Claim-before-evidence — lead with the interface's purpose sentence, then the signature block. -->

### {Component A} → {Component B}
```typescript
// path/to/interface.ts
interface FooService {
  bar(input: BarInput): Promise<BarOutput>;
}
```

## Architectural Diagram

<!-- Per-section guidance: Mermaid diagram of file/module relationships, API endpoints, data flow, interface boundaries. Diagram is written into structure.md (NOT pasted into terminal). Lead with a one-sentence claim describing the diagram's organizing axis (e.g., "Modules grouped by slice; arrows are runtime data flow, not import direction") so a scanning reader does not have to infer the convention. -->

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus