---
description: How to route user intent to the right slash command or skill — detect repo mode (prototype vs production) first, then route.
---

# Skill Selection

When to load a skill — even outside commands. This rule is always active.

## The Rule

**Load a skill only when one of two deterministic conditions is met:**

1. **Match condition** — the user's stated task explicitly matches a skill's trigger phrases (the `description:` field in the skill's frontmatter).
2. **Required condition** — the active command (or active phase of an active command) names the skill via a `REQUIRED SUB-SKILL:` directive or a phase contract.

Neither condition met → don't load. Use the rules-only flow, or suggest `/triage` / `/discover` if the task doesn't fit any workflow. Do not invoke skills heuristically — over-invocation biases the system toward ceremony, pollutes context, and conditions agents to fire on coincidence.

**Single source of truth.** This rule is the only place the loading conditions are defined. `skills/support-system-guide/SKILL.md` references this rule; if the two ever drift, this file wins.

## Repo-state pre-step (mode classification)

When the match condition selects a mode-sensitive skill (e.g. anything in the `iterate-prototype` / `harden` / `build-tdd` family, or when a command's preflight checks call this rule), classify the repo first, then pick the mode-specific variant.

## Step 1: Detect Repo State

Before routing on user intent, classify the repo. **The user-declared `project.mode:` in `.claude/CLAUDE.md` (set during `/setup` Step 2.5) is authoritative.** When present, use it directly — do not run behavioral signal detection.

| Declared mode | Implications |
|---|---|
| `production` | Phase-conditional rules (testing, quality-gates, git-workflow) are active. Production code goes through `build-tdd`. `iterate-prototype` is NOT the default for /feature, /refactor, /bugfix. |
| `prototype` | TDD is exempt (per `rules/common/testing.md` phase header). UI work iterates in-place. Gotchas are recorded but production hardening is deferred. |
| `greenfield` | Treated as `prototype` until the prototype locks, then becomes `production`. |

### Fallback signal detection (only when `project.mode:` is absent)

If `.claude/CLAUDE.md` does not declare `project.mode:` (e.g., pre-Step-2.5 install, or someone deleted the field), fall back to behavioral signals:

| Mode | Signals (any of these) |
|---|---|
| **Prototype** | Path under `pocs/` or directory name ends in `-prototype`; manifest has `phase_plan.prototype: active` and `phase_plan.codify: skipped` |
| **Production** | `aiwiki/architecture/` has entries (codified); manifest has `phase_plan.codify: active` and `phase_plan.production-build: active`; CI configured + tests pass |

**Note: "empty `aiwiki/architecture/`" is intentionally NOT a signal.** Every fresh forge install starts with an empty `aiwiki/architecture/` — using that as a prototype-mode signal would misclassify existing production codebases as prototypes. Use the declared mode instead; if absent, fall back to the behavioral signals above, and if those are ambiguous, ask the user once and persist the answer to `.claude/CLAUDE.md` so future routing doesn't re-ask.

**Mixed mode** (prototype directory inside a production repo, or vice versa) is rare; treat the work item's local context as authoritative — if you're touching files under `pocs/`, you're in prototype mode for that work regardless of the declared project-level mode.

When the mode is ambiguous (no declaration AND no behavioral signal fires clearly), ask the user once and persist the answer. Do not guess.

## Step 2: Priority Rule

When multiple skills match, follow this order:

1. **Diagnose first** — `support-debug` before any fix-skill for bugs
2. **Route by mode**:
   - **Prototype mode**: `iterate-prototype` is the default execution skill. No `build-tdd`, no `harden`, no `plan-architecture` unless explicitly invoked.
   - **Production mode**: `harden` produces architecture/ADRs/slice graph at codify; `build-tdd` implements at production-build.
3. **Review after build** — `quality-code-review` after production code is written (not for prototype iteration; that uses `prototype-reviewer` via `iterate-prototype`)
4. **Plan-* skills are non-prototype fallback only** — `plan-brainstorm`, `plan-architecture`, `plan-task-decompose` are for library / internal-tool / refactor work where prototype/wireframe phases don't apply. Not the default for `/feature` or `/greenfield`.

## Step 3: Direct-Request Routing

| User says / situation | Prototype mode loads | Production mode loads | Why |
|---|---|---|---|
| Bug, error, unexpected behavior | `iterate-prototype` (capture as feedback item) | `support-debug` → `build-tdd` | Diagnose-then-fix is universal; the fix lives in different skills per mode |
| "Add X" / "tweak X" / "improve UI" | `iterate-prototype` | `/feature` (lightweight default — extended phases opt-in at Step 0c) or `build-tdd` if mid-flow | Prototype iteration is lightweight; production features default to lightweight build + gates, with concept / wireframe / prototype / codify available when the work warrants them |
| "Make this fast" / "refactor this" | `iterate-prototype` (mark as iteration item) | `build-tdd` (refactors need tests proving behavior preserved) | |
| Before declaring code changes done | `prototype-reviewer` (informal pass) | `quality-code-review` (full multi-stage chain) | Review depth scales with mode |
| Surprising lesson, workaround, wrong assumption | `support-gotcha` | `support-gotcha` | Mode-independent: writes to `aiwiki/gotchas/` |
| "How should we approach X?" / design discussion | Existing prototype IS the design exploration — answer inline; no skill | `plan-brainstorm` (non-prototype fallback only) | Prototype-driven flow makes brainstorm redundant |
| Need API contracts, DB schema, system design | If a prototype exists, use `harden` to codify; otherwise `plan-architecture` (fallback) | `harden` (from prototype) or `plan-architecture` (fallback) | Codify-from-prototype is the default; plan-* is the fallback |
| New visual direction, design tokens, UI system | `plan-design-system` | `plan-design-system` | Mode-independent design step |
| Security concerns, pre-deploy audit | Not applicable during prototype phases | `quality-security-audit` | Pre-deploy gate; safety floor rules always active |
| Database schema changes needed | Not applicable (prototype data is mocked) | `deliver-db-migration` | |
| Ready to deploy | Not applicable | `deliver-deploy` | |
| New team member needs onboarding | `deliver-onboarding` (light) | `deliver-onboarding` (full) | Same skill; depth varies by mode |

## Ambiguous Requests

Some requests could mean multiple things. Ask before guessing.

| Request | Could be... | How to decide |
|---|---|---|
| "There's no button for X" | Bug (should exist) OR feature (doesn't exist yet) | Ask: "Should this button already exist, or is this a new feature request?" |
| "X isn't working right" | Bug (broken) OR feature gap (never built) | Check if the code path exists. If yes → diagnose. If no → mode-routed feature work. |
| "Can we improve X?" | Refactor OR feature enhancement | Ask: "Is this changing behavior or just restructuring?" Then mode-route. |
| User in production repo says "let me just tweak something" | Production work OR mistaken-for-prototype | Ask: "Is this a one-off ad-hoc change or a tracked feature?" One-off may still need gates if it touches production-built code. |

When genuinely ambiguous, ask — don't guess.

## What This Rule Does NOT Cover

- **Command routing under explicit invocation** — if the user types `/feature`, `/bugfix`, etc., the command's own preflight handles state detection and may redirect (see each command's Step 0). This rule covers routing when the user describes intent without naming a command.
- **Which skill to invoke inside a command** — commands specify `REQUIRED SUB-SKILL` explicitly
- **Skill invocation correctness** — see `skill-compliance.md` for that
- **Prompts that don't fit any workflow command** — if the user's intent isn't `/feature`, `/bugfix`, `/refactor`, `/hotfix`, or `/greenfield` (e.g. research question, monitoring playbook, ad-hoc exploration, "explain this codebase," debugging without a fix), suggest `/triage` instead of forcing a poor fit. `/triage` classifies the work and offers three routes: rules-only ad-hoc, `/feature` with most phases skipped, or document-the-gap-for-`/forge-evolve`.

## The Explicit Rule

- **In production mode**: any production-code change, no matter how small, requires `build-tdd`. "It's just one line" is not an exception. "It's obvious" is not an exception. The skill exists because shortcuts cause regressions.
- **In prototype mode**: code changes use `iterate-prototype` (or inline editing for trivial cases). TDD is intentionally exempt per `rules/common/testing.md` phase header — the prototype's verification surface is manual click-through, not test coverage.

Mode determines which rule applies. Don't apply production discipline to prototype iteration; don't waive production discipline for "this feels like prototyping" inside a production repo.