---
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: Proprietary — Aled Pritchard workspace use.
---

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

## Behaviour

1. **Frame the problem.** 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.

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.** Produce the ADR as a Linear document or a comment on the ticket, in this shape:

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

## Guardrails

- **Specifies, does not build.** Never runs the implementation, never opens a PR with code changes. The deliverable is the ADR. Building is skill-exec, 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-exec.

On finish, run skill-ops-retro capture on this run's friction: file a FRICTION note to the Pulse queue for the drain pass to assess.