Skip to main content
manual page/ ADRs

ADR-0105 — Stretch and collapse: the artifact set is a dial, not a set of stations

sourceSource: suspec/docs/adrs/0105-stretch-and-collapse.mdModified: 2026-06-30
Sections
4
Format
Markdown
Order
141 / 156

Context

The artifact set risks two failure modes: too many stations (ceremony for a trivial change) or too lean (can't unfold for an 8-PR migration). ADR-0103 started the fix (spec is the unit, task on-demand) but it was never stated as a principle, and the kit still ships /examples + /advanced as if every adopter needs every extended-type blank. Ratified from RFC-stretch-collapse (suspec-works#72 ceremony).

Decision

  1. The artifact set is a dial. Default is spec-only; stretch on demand+task when a spec splits into parallel slices, +change-plan for multi-wave migrations, +inventory for brownfield, +research/audit/bug-report/PRD/RFC/ADR when that stance is needed. Nothing is a mandatory station — the complexity of the work summons the artifact; the ephemeral stretch artifacts collapse away after (ADR-0104). Level: convention.

  2. Drop /examples and /advanced from the kit. The extended-type shape belongs in the authoring skills (ADR-0042 one skill per authored artifact; ADR-0016 self-contained bodies), not in loose template files; the deep reference lives in docs/. This refines ADR-0064 (drops the advanced tier + the example). Level: convention.

Consequences

  • The kit slims to the core loop + the skills; offline self-containment yields to single-sourcing (the shape ships in the skills; the reference is one fetch to docs/). docs/examples/ keeps the walkthroughs.
  • Implementation deferred (later plan): each extended-type authoring skill inlines its shape first, then /advanced + /examples are deleted (nothing loses the shape). No change ships with this ADR.

Affected obligations / constraints

  • Refines: ADR-0064 (advanced tier + flagship example). Builds on: ADR-0103. Relies on: ADR-0042 / ADR-0016 (skills carry the shape).
  • Does NOT change: the core templates (spec/task/review/finding), the verdict model, or the checks contract.

Starter kit: Set up a workspace