design

Files (4)

• SKILL.md
• owns-defers.md
• altitude-sub-rules.md · references/
• design-md-template.md · references/

SKILL.md (first lines)

# Design (QRSPI Step 4)

<!-- Soft length target: 200–400 lines for this SKILL.md. The marker is a guidance signal — long enough to carry per-section template guidance + OWNS/DEFERS contract + reviewer wiring, short enough to keep the prompt scannable in a single context window. -->

**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 Design skill to explore approaches and define the architecture."

**If auto-mode is detected** (`## Auto Mode Active` system-reminder present), surface before the first interactive step: "This skill is collaborative — turn-by-turn dialogue produces better Design quality than autonomous execution. Recommend exiting auto-mode (`Shift+Tab`). I'll proceed in either mode if you prefer." Do not force the user out; respect their choice.

## Overview

Translate research findings into per-goal solution definitions through interactive discussion. Propose approaches with trade-offs, surface key architectural decisions with rationale, and lock decisions at outcome altitude. Discussion is conversational; a subagent synthesizes `design.md` per round.

## What Design produces

A per-goal solution definition at outcome altitude — the end-state, the practical solution at the altitude defined by the Altitude Sub-Rules below, and the reasoning. Per-goal acceptance criteria are inline in each goal block. Design MAY include zero or more per-solution diagrams. Unified system architecture, file maps, module boundaries, and the unified test architecture are Structure's job (see Structure's owns/defers contract); per-assertion test code is Plan's job.

## Per-goal block template

- **Outcome** — end-state being targeted
- **Solution** — practical solution at the altitude defined by the Altitude Sub-Rules
- **Why this approach** — tradeoffs and alternatives considered
- **Dependencies + edge cases** — what the solution depends on and which corner cases it handles
- **Acceptance** — high-level "done" signal at the outcome level

**Optional per-goal Mermaid diagram** when the flow benefits from visualization. **Cross-Goal Decisions** section above the per-goal blocks for decisions that span multiple goals.

## Dialogue Conduct

When working a goal with the user, follow these rules.

1. **Open with questions.** Surface open questions for the goal; work through them one decision at a time.

2. **One question at a time, with a recommended answer.** The user confirms, amends, or rejects.

3. **Ground first, ask second.** Consult, in order: the research summary, the codebase, then the web. When a question touches industry best practice or external patterns, search the web for cited evidence rather than speculating or punting back. Escalate to the user only when no source surfaces a defensible answer.

4. **When the user asks for your call, provide one.** Give a grounded recommendation (sources per Rule 3) with named tradeoffs. Do not deflect or punt. If grounding leaves the call indeterminate, say so and name what additional evidence would resolve it.

5. **Use simple language and provide context when presenting ideas.** Ground proposals in concrete scenarios before naming them abstractly. When introducing a technical term that has not appeared in this dialog recently, give one sentence of grounding context. Trade-off framings ("here are 3 candidates: A is X, B is Y...") should explain what each candidate concretely does in plain prose before naming the abstract architectural shape.

6. **Sharpen fuzzy language.** When the user uses imprecise vocabulary, propose the canonical term and ask for confirmation.

7. **Walk every branch of the decision tree, including flow gaps.** Resolve dependencies one-by-one. Do not move to the next goal until every surfaced branch is decided, explicitly deferred with a written reason, or split out as a separate goal. Branch completeness includes the end-to-end flow between multi-actor decisions — actors named, operations sequenced, per-step inputs/outputs traced to producer and consumer, loud-failure paths named, context-cost call-out present (per Sub-Rule C). A flow with implicit hand-offs is an open branch; close it.

8. **Lock decisions as they settle.** Write each decision into the goal block under `status: draft` as it is confirmed. Do not accumulate decisions in chat across multiple goals.

## Altitude Sub-Rule A — Naming-vs-Layout

**Altitude Sub-Rule A — Naming-vs-Layout** (applies to code, scripts, and data-contract artifacts).

Design names artifacts when naming IS the decision. Filenames, script names, contract artifact
names, and renames are in scope when they establish cross-skill vocabulary or commit to a
public-interface identity.

Design does NOT specify:
- Directory trees or where files live within the repo
- Inter-file wiring (what sources / imports / requires what)
- Function or method signatures
- Field-level schema layouts (JSON keys, table columns, struct fields)
- Code, pseudocode, or implementation outlines

**Altitude test.** After reading the design block for a goal, can Structure still author its
file map AND Plan still author its per-task API surface without contradiction? If yes → right
altitude. If no → back off.

**Worked examples.** See `references/altitude-sub-rules.md` § Sub-Rule A.

## Altitude Sub-Rule B — Prose-as-Decision

**Altitude Sub-Rule B — Prose-as-Decision** (applies to prompt prose, reviewer rubrics, skill text, agent frontmatter, dispatch payloads).

When the artifact being designed IS prompt prose, the prose-level wording IS the design. Specifying exact words is not over-reach; it is the unit of architectural commitment. LLM behavior is acutely sensitive to wording, and generic paraphrase is not equivalent to a specified rule.

**Altitude test.** Ask: "if a future agent re-implemented this from my description using different wording, would they produce equivalent LLM behavior?"
- If the artifact is code: generally YES — Sub-Rule A governs; specify what, not how.
- If the artifact is prompt prose: generally NO — Sub-Rule B governs; specify the wording verbatim to the extent scope allows.

**Scope proportionality, operational rule, worked examples.** See `references/altitude-sub-rules.md` § Sub-Rule B for the full proportionality rule, the verbatim-vs-deferred operational block shapes, and the per-artifact worked-example table.

## Altitude Sub-Rule C — End-to-End Flow

**Altitude Sub-Rule C — End-to-End Flow** (applies whenever a design decision introduces or modifies an interaction across two or more actors — orchestrator, script, subagent, file, manifest, external service, user).

When a decision involves multiple actors that hand off to each other, the design block MUST specify the end-to-end flow between them, not just enumerate the components in isolation. "We'll have script X and agent Y and manifest Z" is component enumeration; the design also has to say what calls what, in what order, with what inputs, producing what outputs, consumed by whom.

**Required flow elements** (for any multi-actor decision):
- **Actor inventory** — name every actor (orchestrator, script, subagent, file, external service, user).
- **Sequence of operations** — ordered list of who-does-what. If parallelism matters, name the parallelism boundary (e.g., "M Task tool calls in parallel in one orchestrator response").
- **Per-step inputs and outputs** — what each actor receives and produces. Cite where outputs are written (stdout, file path, manifest entry, Task tool return value).
- **Consumer identification** — name who reads each output next. An output with no named consumer is dead and must be removed or its consumer surfaced.
- **Loud-failure paths** — what happens when each step fails. "Silent fallback" is never the answer — name the diagnostic.
- **Context-cost call-out** — for any flow crossing the orchestrator/subagent boundary, state what enters orchestrator context vs. what stays in subagent context or on disk.

**Altitude test.** Ask: "Can Structure / Plan / Implement enumerate the per-round orchestrator actions in order, naming inputs and outputs for each step, without inventing sequencing decisions the design failed to commit?" If no → back off and add the missing steps. The most common gap is the orchestrator-side instruction work: "the script returns N specs" without saying how the orchestrator parses them and what it does with each one.

**Worked examples, Mermaid-diagram rule, scope clarification.** See `references/altitude-sub-rules.md` § Sub-Rule C.

## Sub-Rule D — External-Knowledge Completeness

**Sub-Rule D — External-Knowledge Completeness** (applies whenever a design decision references behavior, contracts, or signals from external systems — host CLIs, vendor APIs, platform runtime injections, library protocols, third-party file formats).

Design is the LAST research-bearing phase in the QRSPI pipeline. After Design, no skill runs research or external-source verification — Structure, Plan, Parallelize, Implement, Integrate, Test all consume what Design committed. Any external-knowledge question Design defers (a "TBD per vendor docs at implementation time" footnote, a "to be verified by implementer" placeholder) becomes a downstream blocker that resolves to either a guess (silently wrong) or a halt the user has to unblock. Either outcome is a design defect.

The only external-to-codebase knowledge downstream skills are expected to bring is: (a) how existing project code works (they Read it), (b) how to write code in the relevant language (model weights), (c) how to use ordinary development tools (model weights). Everything else — platform behaviors, vendor contracts, host runtime injections, third-party protocols, file-format specifics — MUST be answered in the design block, with citations.

**Required completeness elements** (for any decision that references external behavior):

- **External-claim inventory** — every external-system claim is enumerated explicitly. Implicit references ("the platform handles it", "see vendor docs") are forbidden — name the platform, name the mechanism, write the answer.
- **Verified answer** — each claim has the concrete answer in the design block, not deferred.
- **Source citation** — each claim cites its source: docs URL + fetch date, CLI command + output snapshot, direct runtime observation + observation method + observed value.
- **Verification method label** — note whether the answer was verified by docs-only, docs + direct observation, or direct observation only. **For claims about host runtime injections, direct observation is required** (doc-only is unreliable — host CLIs frequently inject undocumented signals; verified case: Copilot CLI v1.0.57 injects an autopilot-state context tag with no mention in `copilot help environment` or official autopilot docs — see `scripts/detect-interaction-mode.sh` for the exact tag and sentinel literals). <!-- evergreen-exempt -->
- **Unknown branches** — when verification yields "unknown" or "host-not-yet-supported", the design block MUST name the unknown AND specify the safe-default downstream code applies AND the verification procedure the implementer follows when the host is added. "Unknown — safe default X — verify via procedure Y" is valid; "TBD figure out later" is not.

**Completeness test.** Ask: "If a fresh implementer reads only this design block plus the existing project code, can they implement the decision without consulting any external source the design didn't already cite?" If no → name the missing external answer, research it, write the answer + citation. If genuinely unknown, add an explicit `unknown` branch with safe-default + verification procedure.

**Worked examples and scope clarification.** See `references/altitude-sub-rules.md` § Sub-Rule D.

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus