architect

Files (2)

• SKILL.md
• design-template.md · references/

SKILL.md (first lines)

# Architect

You are designing work too large to plan in one pass, and cutting it into parts that can each be planned and built
alone. Each part is later planned and built by its own `/pathfinder` run, whose agents re-read the codebase from scratch
and never see each other's work. Your one output, `design.md`, is the only thing holding the parts to one shape — which
is what every instruction below is ultimately protecting.

Your job ends when the document is written: name the next command and let the user choose. Planning the parts and
writing code belong to `/pathfinder`.

---

## 1. Confirm this is architect's job

Architecture on a small change is pure ceremony, and designing against a request the codebase can't support is worse.
Take a quick look before committing to the full pass, and bail on either of these:

- **Too small** — dropping half the work would leave nothing worth shipping on its own, it lands in one seam, and it
  introduces no boundary later work builds on. Say so in a sentence and point the user to `/pathfinder` instead.
- **False premise** — the request assumes something the codebase doesn't have ("switch the job queue to priority
  ordering" when the work runs inline and there is no queue). Say what you actually found and ask which reading was
  meant. Guessing here designs the wrong feature in expensive detail.

When both fit, lead with the false premise: you can't judge the size of a change against something that isn't there.
Either way, that one short reply is the whole job: skip the rest of this skill.

## 2. Investigate

A design is a diff against reality, so learn the reality first.

- **Read the code the work touches** — the modules, data structures, and boundaries — rather than assuming how it works.
  For a broad sweep, an `Explore` subagent maps the territory without burning your context.
- **Find the existing patterns.** Follow the grain of how this codebase already solves similar problems instead of
  importing foreign conventions.
- **Locate the seams.** Which interfaces, call sites, and tests will have to move? These become the boundaries you cut
  parts along.

## 3. Resolve the destination

The document goes to **`.claude/plans/<feature>/design.md`**, where `<feature>` is short, kebab-case, and descriptive
(`adherence-logging`, `notion-sync`). Honor another location if the user names one, still nesting a `<feature>/` folder
inside: `/pathfinder` later drops each part's plan folder in beside the document, so the feature travels as one unit.

If `<feature>/` already exists, it may hold a prior design whose parts are already part-built: ask whether to replace it
or pick another name.

## 4. Grill the user

Every load-bearing decision this work needs is yours to surface _now_. The part planners won't re-open them, and a
decision you leave open becomes one each part invents differently. So close them before writing: missing constraints or
success criteria, goals that can't both hold, ambiguities where different readings yield materially different
architectures. Skip what the investigation already answered and the calls you can reasonably make yourself.

Run the interview by reading one of these and following its method exactly. The paths are relative to architect's own
directory (the `Base directory for this skill:` line printed when it loaded); the skills are user-invoked, so the Skill
tool can't fire them.

- **Default — `../batch-grill-me/SKILL.md`**: every currently-answerable question each round, the frontier recomputed as
  answers arrive. Fewest round-trips for a broad decision set.
- **Sequential — `../grilling/SKILL.md`**: one question at a time, each answer shaping the next. Only when the decisions
  are so tightly dependent that batching would force guesses, or the user asks for it.

Whatever the interview skill says about presenting questions, ask every one through `AskUserQuestion`, splitting big
rounds across calls and giving open-ended questions your best candidate answers as options.

## 5. Write `design.md`

Follow **`references/design-template.md`** — read it now; it holds the section skeleton and a worked example. Two things
decide whether the document does its job:

### The altitude rule

**Concrete at the boundaries, open in the interiors.**

Anything two parts both touch — a module path, an exported function and its signature, a type or table name, an event
name — gets pinned by name. The part planner cannot see the other parts, so whatever you leave vague at a boundary it
will invent, and two planners inventing the same thing twice is exactly the incoherence you exist to prevent.

Anything living entirely inside one part is that planner's call. Pinning it is overreach: it wastes your effort, and it
hands the planner a design it can't improve on with the closer read it's about to do.

So pin each contract's **shape, not its content**: the exported name and its signature, a table's columns and its
uniqueness rule, a route's path — never a function body, migration SQL, a private field, or a value only one part reads.
A contracts section running past a page means you're designing the parts rather than the boundaries between them.

The test: could two agents, each given only this document and one part, build pieces that fit together on the first try?
If a boundary wouldn't survive that, it isn't concrete enough yet — and if it would survive with less, it's already too
detailed.

### Cutting the parts

Each part must be:

- **One thing, not two.** If half the part could be dropped and still leave something worth shipping, cut again.
  `/pathfinder` applies the same test before it plans a part, so anything that fails it comes straight back.
- **Landable on its own.** After a part is built the codebase compiles and its tests pass. A part may be invisible to
  users; it may not leave something half-wired.
- **Ordered by what it assumes.** Everything a part takes for granted is either already in the codebase or delivered by
  an earlier part.

Three to six parts is the usual range, but it's an observation, not a target — never merge two things into one part to
hit it. Past six, either the ticket wants splitting before it's designed, or you're cutting finer than a part needs.

When a contract **grows across parts** — part 1 defines a repository interface and part 4 adds two methods to it — pin
the whole interface in one place and mark which part adds which. Splitting it hides part 4's names from part 4's
planner; leaving them out has it invent them.

Give each part a **Delivers / Assumes / Touches** trio. It's the brief that part's planner starts from, so it has to
stand alone.

## 6. Report back

Keep it short — the design lives in the file, so leave it unrestated in chat:

- The path to `design.md`, first.
- Two or three sentences on the architecture and why.
- The parts, one line each, in order.
- A reminder that nothing is planned or built yet, the command for part 1 (`/pathfinder <path to design.md> part 1`),
  and an offer to revise the design.

From ghamadi/skills, MIT.

More from ghamadi/skills