# Routing Table — Conditional Applicability Matrix

neckbeard owns the **cross-stage contracts**: the change contract, the evidence
ledger, the stop/escalation rules, and the evaluation protocol. It does **not**
own domain method. When a stage has a specialist skill, load it and follow it
instead of re-deriving its method here.

This matrix prevents the omnibus bundle from swallowing the specialist catalog.
Each row carries a concrete **applicability signal** (an observable,
file-system- or artifact-based criterion) and a concrete **skip rule** (its
observable complement). Evaluate every row against the change surface; record
each skip with its reason in the delivery packet
([delivery-packet.md](delivery-packet.md), group (e)). Silent omission is
prohibited.

**Platform neutrality.** This routing matrix works for both public OSS
repositories and private/enterprise development contexts. GitHub is a documented
reference mode, not the only possible platform. The `opensource-contributions`
row is conditional on public/OSS repositories; for private or enterprise-internal
repositories, enterprise contribution governance applies instead (see
[lifecycle.md](lifecycle.md), enterprise mode). No row assumes public-repo
defaults without qualification.

## Routing matrix

| Catalog skill | Applicability signal | Skip when | neckbeard provides |
|---|---|---|---|
| `product-discovery` | Change request text lacks testable acceptance criteria, no `SPEC.md` or requirements artifact accompanies it, or scope is contested among stakeholders | Scope is fully specified in the change request with testable acceptance criteria and no stakeholder ambiguity | Contract, ledger |
| `product-methodology` | Multiple competing requirements documents, backlog items, or priority-conflicting issues reference the same feature area; sequencing or prioritization decisions must be recorded | Requirements are singular and uncontested; no backlog, roadmap, or prioritization document needs updating | Contract, ledger |
| `product-design-and-ux` | Change creates or modifies view templates, component files, route definitions, interaction flows, information architecture, or UI-state logic | No view template, component, route definition, interaction flow, information-architecture artifact, or UI-state logic is created or modified | Contract, ledger |
| `spec-driven-development` | Work requires a formal specification with phase gates, acceptance-criteria mapping, and structured decomposition (`SPEC.md`, `TASK-PLAN.md`) | Change is a single-surface fix fully described by the change contract; no separate `SPEC.md` or phased decomposition is needed | Contract, ledger, stop rules |
| `software-architecture-analysis` | Change modifies or requires understanding of module boundaries, service dependencies (`go.mod`, `package.json` dependency graph, import graphs), cross-service contracts, or system-level structure | Change is confined to a single function or module with no cross-component dependency, service boundary, or system-level structure change | Ledger, assumptions list |
| `c4-diagramming` | Architecture change spans multiple containers or services and the design record requires system context, container, component, or code-level diagrams for review | Change fits within a single container or service; no multi-system diagram is needed for the design record | Ledger |
| `adr-authoring` | A consequential, hard-to-reverse technical decision (storage engine, framework, protocol choice) must be recorded in a decision record with context, alternatives, and consequences | No consequential decision beyond what the change contract already captures is required; no decision-record file is needed | Decision-record template, ledger |
| `api-design-and-evolution` | Change modifies or creates a public API surface: OpenAPI/AsyncAPI specs, protobuf/gRPC definitions, REST endpoints, GraphQL schema, webhook contracts, or SDK interface | No public API surface, interface contract, or protocol definition is created or modified | Contract, ledger, boundary verification |
| `systematic-debugging` | Change request reports a bug, failure, or regression; error logs, stack traces, or reproduction steps accompany it; root-cause analysis is needed before a fix can be designed | Change is not a bug fix; no error log, stack trace, or reproduction evidence accompanies the request; the desired behavior is already known | Contract, ledger, boundary verification |
| `secure-software-engineering` | Change touches auth modules, middleware handling untrusted input, secrets-management files, cryptographic operations, or code that crosses a trust boundary (e.g., `auth/`, `middleware/`, `crypto/`, input-validation handlers) | No auth module, untrusted-input handler, secrets file, crypto operation, or trust-boundary-crossing code is in the change surface | Contract, ledger, trust-boundary checks |
| `security-audit-methodology` | A security audit artifact (`SECURITY-AUDIT.md`, threat model, STRIDE analysis) is requested, or the change touches auth/crypto/trust-boundary files and a post-build vulnerability review is required | No security audit artifact is requested and the change surface does not include auth, crypto, or trust-boundary files requiring post-build review | Ledger |
| `web-accessibility` | Change modifies user-facing markup, styles, ARIA attributes, keyboard/focus contracts, or error-recovery UI; WCAG conformance is in scope | No user-facing markup, style, ARIA attribute, keyboard/focus contract, or error-recovery UI is created or modified | Ledger, non-negotiable confirmation |
| `qa-methodology` | A `VERIFICATION-PLAN.md` or test-strategy artifact is required, CI quality-gate configuration is modified, or independent verification-plan ownership is needed before implementation | Change requires no `VERIFICATION-PLAN.md`, no CI quality-gate modification, and no independent test-strategy artifact beyond the implementer's own focused tests | Ledger, boundary verification |
| `technical-documentation` | Change creates or modifies user-facing docs, README, API reference, guides, or inline documentation intended for consumers | No user-facing documentation, README, API reference, or guide is created or modified | Ledger |
| `verification-methodology` | A `VERIFICATION.md` verdict artifact with layered evidence (PASS/FAIL/BLOCKED/NOT-APPLICABLE) is required at the delivery boundary | Verification is a single focused test run that does not produce a `VERIFICATION.md` artifact or need the structured verdict protocol | Ledger, boundary rules |
| `release-engineering` | Change modifies version files, changelogs, release configuration, pipeline promotion rules, rollout strategy, or rollback procedures | No version file, changelog, release configuration, pipeline promotion rule, rollout strategy, or rollback procedure is created or modified | Contract, ledger, rollback evidence |
| `site-reliability-engineering` | Change modifies SLO/SLI definitions, incident response runbooks, operational recovery procedures, monitoring dashboards, or alerting configuration files | No SLO/SLI definition, incident runbook, operational recovery procedure, monitoring dashboard, or alerting configuration file is created or modified | Contract, ledger, rollback evidence |
| `platform-engineering` | Change modifies infrastructure-as-code, deployment pipelines, container/orchestration configuration, or platform-level provisioning files | No infrastructure-as-code, deployment pipeline, container/orchestration configuration, or platform provisioning file is modified | Contract, ledger |
| `programming-principles` | Change is primarily a refactoring (files renamed/moved/split without behavior change), code-review request, or quality assessment; diff touches many files with structural reorganization | Change is greenfield implementation or a targeted bug fix; no structural reorganization, review request, or quality assessment is the primary objective | Contract, ledger, boundary verification |
| `backend-engineering` | Change modifies server-side logic, service architecture (clean/hexagonal/layered), database access patterns, API implementation code, middleware, or service-to-service integration | No server-side logic, service architecture, database access pattern, API implementation, middleware, or integration code is modified | Contract, ledger |
| `frontend-engineering` | Change modifies client-side application code, component hierarchy, state management, browser APIs, or UI rendering logic | No client-side application code, component, state management, browser API, or UI rendering logic is modified | Contract, ledger |
| `mobile-development` | Change creates or modifies mobile app source for iOS, Android, Flutter, or React Native (`*.swift`, Kotlin sources, Flutter `lib/` Dart files, React Native components and Metro config) | No mobile app source file is created or modified; the change is web frontend or backend only | Contract, ledger |
| `documents` | A deliverable is required in office-document format (PDF, Word, Excel, PowerPoint) for human stakeholders — a report, memo, spreadsheet, or deck generated from the change | The deliverable is markdown or the repository's native format; no office-format artifact is requested | Contract, ledger |
| `cli-builder` | Change creates or modifies a command-line interface: argument parsing, flag design, subcommands, `--json` output, `--dry-run` preview, or exit-code contracts | No CLI argument parsing, flag, subcommand, or CLI output contract is created or modified | Contract, ledger |
| `data-engineering` | Change modifies database schemas, migration files (`migrations/`, `*.sql`), ETL/ELT pipelines, data quality checks, or analytical SQL | No schema, migration file, ETL/ELT pipeline, data quality check, or analytical SQL is created or modified | Contract, ledger |
| `data-architect` | Change requires a data-model design artifact, storage-platform evaluation, data-governance definition (ownership, lineage, cataloging), or cross-system data-flow diagram before implementation | No data-model artifact, storage-platform evaluation, data-governance definition, or cross-system data-flow design is required; schema changes are mechanical | Contract, ledger |
| `agent-evals-and-observability` | Change modifies AI/agent behavior: eval definitions, agent task contracts, grader bindings, trajectory fixtures, prompt templates, or agent observability/telemetry | No agent eval, task contract, grader, trajectory fixture, prompt template, or agent telemetry is created or modified | Contract, ledger |
| `opensource-contributions` | **Conditional — public/OSS repos only.** Repository remote is public, an open-source license is present, and a `CONTRIBUTING.md` or equivalent contribution governance file exists (verify via repo remote or `gh api`); contribution norms, agent disclosure, or fork etiquette apply | Repository is private or enterprise-internal (non-public remote, no open-source license); record skip as "non-public repository." Also skip when no contribution-norm question arises even in a public repo | Contract, ledger |
| `linear` | The product's tracking system was identified as Linear by [tracker-discovery.md](tracker-discovery.md) during intake, and tracker operations are needed (read/update work items, transitions, comments) | Tracking system is not Linear; or the change needs no tracker operation beyond reading provenance already captured | Contract, ledger |
| `jira` | The tracking system was identified as Jira by [tracker-discovery.md](tracker-discovery.md), and tracker operations are needed | Tracking system is not Jira; or no tracker operation is needed beyond captured provenance | Contract, ledger |
| `notion` | The tracking system was identified as Notion by [tracker-discovery.md](tracker-discovery.md), and tracker operations are needed | Tracking system is not Notion; or no tracker operation is needed beyond captured provenance | Contract, ledger |

## Test-hardening evidence

When the change is a focused regression guard for already-correct production behavior (the lightweight test-hardening path, [lightweight-test-hardening.md](lightweight-test-hardening.md)), the `qa-methodology` row supplies the evidence format: use its bounded mutation-review record ([templates/mutation-review.md](../../qa-methodology/templates/mutation-review.md)) and mutation-guided hardening methodology ([references/test-automation.md](../../qa-methodology/references/test-automation.md)) when the repository already runs mutation testing. The lightweight-path contract still governs applicability and evidence thresholds.

## Change-surface coverage

Every mandated change surface maps to at least one row above. When a change
request touches one of these surfaces, the corresponding row's applicability
signal triggers:

| Change surface | Routing row(s) |
|---|---|
| Ambiguous scope | `product-discovery`, `product-methodology` |
| User-facing behavior | `product-design-and-ux`, `frontend-engineering`, `web-accessibility` |
| Architecture | `software-architecture-analysis`, `c4-diagramming`, `adr-authoring` |
| API/interface | `api-design-and-evolution` |
| Data (schema/migration) | `data-engineering`, `data-architect` |
| Implementation domain | `backend-engineering`, `frontend-engineering`, `mobile-development`, `cli-builder` |
| Mobile app code | `mobile-development` |
| Office-format deliverables | `documents` |
| Security | `secure-software-engineering`, `security-audit-methodology` |
| AI/agent behavior | `agent-evals-and-observability` |
| Documentation | `technical-documentation` |
| Operational | `site-reliability-engineering`, `platform-engineering`, `release-engineering` |

Additional rows serve cross-cutting stages: `spec-driven-development`
(specification and decomposition), `systematic-debugging` (root-cause analysis),
`qa-methodology` (test strategy and verification planning),
`verification-methodology` (structured verdicts), and `programming-principles`
(implementation quality review).

## Multi-row composition

When several applicability signals trigger for one change (e.g., backend +
API + schema/migration), specialists **compose by stage**:

- **One lead per stage.** Each stage has exactly one lead specialist. No two
  rows own the same stage simultaneously.
- **Record per-stage leads.** The delivery packet group (e) records each
  selected skill with its stage lead — for example,
  "`backend-engineering` (lead: implementation),
  `api-design-and-evolution` (lead: contract design),
  `data-engineering` (lead: migration)."
- **Skipped rows still recorded.** Every row whose signal did not trigger is
  listed with its skip-rule reason, per the skip-transparency rule above.

## No-specialist-needed fallback

When **no** row's applicability signal triggers, work proceeds on the neckbeard
spine using the minimal stage methods in [stages.md](stages.md). The delivery
packet records: **"no specialist selected — no applicability signal triggered."**
This is a legitimate routing decision — not a silent omission and not a
fabricated skip reason.

## "Use the existing skill instead" conditions

Route entirely to a specialist — do **not** run the neckbeard spine — when:

- The task is a pure documentation job with no delivery-boundary risk →
  `technical-documentation`.
- The task is a self-contained debugging request and the user only wants the root
  cause and fix → `systematic-debugging` (neckbeard's ledger is still worth
  appending if the fix is non-trivial).
- The task is a formal spec authoring exercise → `spec-driven-development`.

## When no specialist is installed

neckbeard's [stages.md](stages.md) gives a minimal fallback method per stage.
Use it, but record in the ledger that the specialist skill was absent, so a
reviewer knows the method was the fallback rather than the full specialist.

## What neckbeard never does

- It does not re-implement a specialist's internal method.
- It does not override a repository's own contribution rules, review process, or
  human accountability.
- It does not automate privileged, destructive, deployment, or merge actions
  beyond the host agent's existing authority and confirmation controls.
- It does not treat a benchmark win as proof of production effectiveness.