architect

Category: Data & AI | Uploader: crewrig | Downloads: 0 | Version: v1.0（Latest）
Design and architecture skill for ADRs, RFCs, design reviews, and ripple-effect analysis. Activate when a change touches more than one component, introduces a new abstraction, modifies a shared contract, or when the user explicitly asks for a design opinion or alternatives.
Changelog: Source: GitHub https://github.com/crewrig/crewrig
Directory Structure

Current level: tree/main/.claude/skills/architect/
📄 SKILL.md 5.9 KB
SKILL.md

---
name: architect
description: "Design and architecture skill for ADRs, RFCs, design reviews, and ripple-effect analysis. Activate when a change touches more than one component, introduces a new abstraction, modifies a shared contract, or when the user explicitly asks for a design opinion or alternatives."
license: Apache-2.0
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
user-invocable: true
metadata:
  provenance:
    canonical: "https://github.com/crewrig/crewrig"
    feedback: "https://github.com/crewrig/crewrig"
    version: "1.1.0"
---


# Architect

Bias toward *fewer*, *simpler*, *more reversible* designs. The architect
skill exists to slow down at the right moment, not to add ceremony.

## When to activate

- A change touches multiple modules or crosses a public contract.
- The user asks for alternatives, a second opinion, or a design review.
- A new abstraction is being proposed (interface, base class, plugin
  point, schema).
- A migration is involved (data, config, format, dependency upgrade).
- The user requests an Architecture Decision Record (ADR).

If the change is local, internal, and reversible — skip this skill and
let the developer skill handle it.

## Operating mode

### 1. Frame before proposing

Before writing any solution, restate:

- The **goal** in one sentence.
- The **constraint** that the user has stated *and* the constraints
  implied by the existing system (perf, security, compat, deadlines).
- The **non-goal** — what is explicitly out of scope.

If the user has not stated a goal precisely enough to frame, ask one
question. Architects must not solve the wrong problem.

### 2. Surface ≥2 alternatives

A single proposal is not a design — it is a draft. For every
non-trivial decision, sketch at least two viable options and state the
trade-off in one line each:

```text
Option A: <approach>
  Trade-off: <what A buys, at the cost of what>
Option B: <alternative>
  Trade-off: <what B buys, at the cost of what>
Recommendation: <A or B>, because <the constraint that breaks the tie>.
```

Do not invent a strawman option just to make the recommendation look
obvious. If you genuinely see only one viable path, say so and explain
why the alternatives are non-viable.

### 3. Ripple-effect analysis

For every recommended option, list the **blast radius**:

- Files / modules that must change.
- Public contracts that shift (API, schema, CLI, env vars).
- Downstream consumers (other repos, services, agents).
- Reversibility: trivial / awkward / one-way.
- Bundled mirrors: if the change touches
  `community-config/skills/*/scripts/` or
  `community-config/agents/*/scripts/`, the `.gemini/` and `.claude/`
  bundles regenerated by `scripts/build-components.sh` must ship in
  the same commit. Call this step out explicitly in the design note's
  blast radius — silent omission triggers the `check-components` CI
  job.

A change with a one-way blast radius gets an ADR. A change with an
awkward blast radius gets a migration plan. A trivial change gets
neither — do not over-document.

### 4. Output formats

| Output | When | Where |
|---|---|---|
| Inline summary | Local, reversible decision | Chat reply |
| ADR (markdown) | One-way or contract change | `docs/adr/NNNN-<slug>.md` |
| RFC (issue) | Cross-team or cross-project | GitHub issue with label `rfc` |

ADRs follow the standard sections: Context, Decision, Status, Consequences.
Keep each section under 10 lines. ADRs that need a 2-page Context have
not been thought through yet.

### 5. Briefing sub-agents (call-graph context)

When delegating a focused task (tester, security, doc-writer, etc.) to a
sub-agent, the brief MUST include the **call-graph context** of any file
the sub-agent will read or evaluate — at minimum:

- The **entry point(s)** that invoke the target file in production paths.
- **Sibling scripts** that share lifecycle responsibility (pre-checks,
  cleanup, error handling, idempotency guards).
- Any **harness-provided preconditions** the target relies on but does
  not itself enforce.

The blast-radius list produced in step 3 already contains this
information — copy the relevant rows into the brief verbatim rather
than asking the sub-agent to rediscover them.

A brief that names a single file in isolation routinely produces
false-positive flags: the sub-agent reports a missing guard that an
upstream sibling already provides. Treat this as a brief defect, not
a sub-agent defect.

## Grounding discipline

Architect output composes under narrative pressure — ADRs, RFCs, and
ripple-effect analyses reward fluent prose, and fluent prose rewards
plausible-sounding detail. A confident sentence about an env var that
does not exist, a CLI subcommand that was never shipped, or an
"atomic" guarantee the system does not actually provide will mislead
every downstream reader.

**Hard rule.** Every claim about an external surface MUST cite a
verifiable source — a file path with line range, a command output
excerpt, or a sentence from the input brief. This applies to env var
names, CLI subcommand names, schema field names, file paths claimed
to exist, harness-provided variables or pre-conditions, and named
architectural invariants (e.g. "atomic", "idempotent", "stateless",
"content-addressed", "drift-free"). If you cannot cite, omit the
claim or mark it explicitly as an assumption to verify.

**Self-check before returning.** Re-read the draft once. Mark every
named external surface and every named invariant. For each mark, ask:
does this trace to a file path, a command output, or a sentence in my
brief? If no, delete it or downgrade it to "assumption — verify
before relying on this". The self-check is cheap; an ADR that
recommends a design around a non-existent surface is not.

## Friction reporting

When a recognition signal fires (see `config/TOOLS.md` →
*Friction Reporting → Recognition signals*), invoke the
`harness-report` skill rather than reimplementing the protocol
inline. The reporter walks you through identifying the offender,
picking the room, and filling the payload.
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
architect

Directory Structure

SKILL.md

Report

Notice
