---
name: "skill-architecture-spike"
type: skill
description: Research and specify a technical approach before any code is written, on behalf of the Forge role. Use this whenever a ticket or problem needs a design decision first — investigate the options against the repo and the conventions, then produce a written architecture decision record (the problem, the options with trade-offs, the recommendation and why, and the resulting build steps) attached to the ticket for Aled or Relay to turn into build tickets. This spike does not implement and never opens a PR with code changes — its deliverable is the ADR. Trigger it whenever the task is to scope, spike, design, or decide an approach before building, rather than to build.
license: CC BY-NC-SA 4.0
---

# architecture-spike

The thinking that comes before the building. Given a ticket or a problem, this investigates the options against the actual repo and the conventions, weighs the trade-offs, and writes an architecture decision record (ADR) the operator and Relay can turn into well-shaped build tickets. It is the Forge role in its design mode — it decides the approach so that skill-build-ticket can build it cleanly. Follows convention-github, convention-linear, and the gate policy (Aled decides what gets built).

This skill **does not implement**. Its deliverable is the ADR, not code. It never opens a PR with code changes.

## Trigger

A ticket or problem that needs a design decision before it can be built — a non-trivial change, more than one plausible approach, a new dependency or pattern, or a request to "spike", "scope", or "decide how to" do something. Delivery projects only; never the Pipeline team. If the approach is already obvious and agreed, there is no spike to run — say so and route to skill-build-ticket instead.

## Behaviour

1. **Frame the problem — and verify every figure the ticket asserts before adopting it as a constraint.** Read the ticket and its context. State plainly what is being solved and what a good solution must satisfy — the constraints, the success criteria, anything explicitly out of scope. Before any of those become the frame, check each **figure, premise or measurement the ticket asserts against its generating source** — the token file for a design-system value, the decision-log entry for a ruled figure, the spec for a stated behaviour — the spike-side equivalent of `skill-build-ticket` step 3a's repo premise-check. For a design-system chain the token file outranks the decision log: it is what production renders from and it is machine-checkable. Where the assertion does not hold, say so in the ADR's context section and **reframe the problem against the true value rather than measure against the false one** — step 4 recommends against this step's criteria, so an unchallenged premise here propagates into the measurement plan and the verdict. (Worked case: A1-338 asserted the nav marks render at "16px (640)" and asked for proportion to be measured across 40px and 16px; `size/nav-mark` in `tokens/semantic.tokens.json` is a flat 40px with no mobile mode, and the 16px belonged to `size/selector`. Measured at face value the spike would have recommended a token model for a responsive mode the product does not have — APP-971.)

2. **Investigate against the repo.** Read the relevant parts of the connected repo — existing patterns, the structure, the dependencies already in use, how similar problems were solved before. Read convention-github and any domain conventions (convention-vercel, convention-sanity, and so on) that bear on the choice, so the recommendation fits the system rather than fighting it.

3. **Lay out the options.** Identify the genuine candidate approaches — usually two or three. For each: how it works in this codebase, what it costs, what it buys, and the risks. Be honest about trade-offs; a one-option ADR is a decision dressed up, not a spike.

4. **Recommend.** Pick one approach and say why it wins against the criteria from step 1 — the reasoning, not just the verdict. Note what the recommendation gives up.

5. **Break it into build steps.** Turn the recommendation into the concrete steps a build would take — enough that Aled or Relay can split it into well-scoped build tickets (each a leaf, sized for one PR). Flag anything that should be its own ticket, any sequencing or blocked-by relations, and any open question still needing Aled's call.

6. **Write the ADR and attach it.** The ADR is a Linear **document**, never a comment on the ticket — a comment cannot be cited from a follow-on ticket, a later spike or the decision log, and it scrolls out of sight down the thread. File it in the ticket's own project, titled `<project>.adr.<slug>` per convention-linear's document type-prefix rule — that convention is the home of the naming form, so read it there rather than deriving a name per run — and attach it to the spike ticket as a native Linear **Link**, so it sits in the sidebar as a titled reference the build tickets and the decision log can cite. It takes this shape:

   **The decision leads; the Problem → Options sequence is the audit record beneath it.** The shape below is an *audit* order, and the ADR's first reader is the Owner or Relay deciding what to build — so `convention-comms-owner`'s header rule governs the opening: above `## Problem`, a scannable block giving the **Decision** (the recommendation in one line), the **Action needed** (whose call it is and what it is), and **Why** in one or two plain sentences, with the full reasoning staying below for the audit reader. Do not reorder the sections to achieve it and do not restate the argument in the header. A spike ticket asking for "options considered and rejected, with the recommendation first" is therefore satisfied by the header rather than by a departure from this template; a run that does depart says so in its hand-off. (Worked case: APP-2082, the design-token standards spike, 2026-10-06 — the ticket's expected output asked for the recommendation first, the run followed the ticket and departed from this template, and nothing in this skill said the two were reconcilable — APP-2093.)

   ```
   ## Problem
   [what is being solved and what a good solution must satisfy]

   ## Options considered
   [each option: how it works here, trade-offs, risks]

   ## Recommendation
   [the chosen approach and why it wins; what it gives up]

   ## Build steps
   [the concrete steps, ready to become build tickets — note sequencing,
    blocked-by relations, and any open question for Aled]
   ```

7. **Hand off.** Leave the ADR on the ticket for **Aled or Relay** to turn into build tickets. Do not create the build tickets unilaterally and do not move the ticket into a build state — shaping the queue is Relay's, deciding what gets built is Aled's. Report what was decided and what now needs his or Relay's call.

 **A ticket's own "Expected output" naming a follow-on ticket is satisfied by the ADR's recommendation, never by creating that ticket.** This is the same shape as the header-ordering case above and the more expensive end of it: there, following the ticket's wording departed from a template, while here it would breach the gate the skill exists to hold, since creating the build ticket is the act reserved to Relay and deciding what gets built is the Owner's. So an expected output reading "a single upgrade ticket if clean, separate prep and upgrade tickets if blockers are found, or a human-action ticket if the Owner must act first" is a request for the **routing recommendation** — which of those three shapes the work should take, and why — and it is met in the ADR's Decision header and Build-steps section, with the hand-off naming the shape recommended and whose call it now is. Read it that way without treating the ticket as malformed. The authoring-side half belongs with `convention-ticket`'s spike format, where an expected output is phrased as a recommendation on how to route rather than as an instruction to create. (Worked case: A1-800, the Sanity v6 upgrade-requirements spike on the meirionpritchard-com studio, 2026-10-23 — the ticket's expected output listed the three ticket shapes, the run wrote the ADR with a clean-bump recommendation and the concrete build steps, created no ticket, and said so in the hand-off. The right resolution, reached as a judgement call in the moment with nothing in canon settling it — APP-2646, after APP-2093.)

## Guardrails

- **Specifies, does not build.** Never runs the implementation, never opens a PR with code changes. The deliverable is the ADR. Building is skill-build-ticket, after Aled or Relay has turned the spike into build tickets.
- A throwaway prototype branch may be cut to *learn* (to test whether an approach is viable), but it is never offered as the change — its only output is evidence that feeds the ADR, and it is not turned into a PR for merge.
- Does not decide what gets built — it recommends; Aled is the gate. Does not shape the queue into tickets — that is Relay.
- Reads broadly, writes one artefact. The ADR is the single source of the decision, kept on the ticket so it is in the canonical record.
- Scope to delivery repos only. Never touches the Pipeline team's work.

## Setup

- Runs on the **Linear** and **GitHub** connectors — GitHub read access is enough (it investigates, it does not push code).
- Routine prompt or ad hoc: "Run the architecture-spike skill on [the ticket]."

Owned by **Forge** (`F0-RGE`) — the implementation role, here in its design-first mode ahead of skill-build-ticket.

On finish, run skill-ops-retro capture on this run's friction: **search the Pulse queue first and add the evidence to a same-root note if one exists, otherwise file a new FRICTION note** for the drain pass to assess, in capture step 3's literal shape — team Apps, project os.Claude, `FRICTION:` title, labels `task` + `work:configuration` + `PUL-5E`, Backlog, unassigned — filing the friction, never the run report.
