skill: constitution

# Prompts that MUST load the `constitution` skill. It is the FIRST rsc-sdd phase:
# capture a project's non-negotiable principles (stack canon, quality bars,
# conventions, branching/security/a11y floors) into 02-DOCS/wiki/sdd/constitution.md,
# reconciling with 02-DOCS/wiki/stack/*. It NAMES bars and links enforcers; it does
# not describe a feature (specify) or design an implementation (plan).
should_trigger:
  - prompt: "Let's set the non-negotiable principles for this project before we start building features."
    why: "Capturing project-wide non-negotiables once, up front, is the exact purpose of the constitution phase."

  - prompt: "I want a project constitution: stack canon, the quality bar, and our coding conventions in one place."
    why: "Names the artifact and the three pillars (stack canon, quality bar, conventions) the skill produces."

  - prompt: "We keep relitigating test coverage and branch naming — can we ratify these as project rules once and for all?"
    why: "Turning repeatedly-relitigated decisions into ratified, enforceable principles is a core trigger, phrased without naming the skill."

  - prompt: "Amend our engineering standards to require strict TypeScript and bump the version."
    why: "Amending a ratified principle with a version bump is the amendment protocol this skill owns."

  - prompt: "What's the definition of done for the whole repo that every PR has to pass?"
    why: "The repo-wide Definition of Done (the merge bar verify runs against) lives in the constitution, not in any single feature spec."

  - prompt: "Lock down our stack canon and quality floors so the SDD phases have guardrails to read."
    why: "Explicitly the guardrail document every later SDD phase reads — the constitution's defining role."

  - prompt: "Write our project's coding standards doc — formatter must pass clean, types strict, secrets never committed."
    why: "These are enforceable project-wide non-negotiables (quality bar + security floor), the constitution's content."

  - prompt: "Establecer las reglas del proyecto: convenciones de nombres, cobertura mínima y cómo hacemos los commits."
    why: "Spanish phrasing for setting project-wide conventions, coverage floor, and commit rules — all constitution principles."

# NEAR-MISS prompts that must NOT load `constitution`. Each routes to the genuinely
# correct sibling that exists in this repo. The recurring trap: anything that sounds
# like 'project setup' or 'standards' but is actually a feature, a stack mechanic,
# the wiki scaffolding, or a security implementation.
should_not_trigger:
  - prompt: "Set up 01-TOOLS and 02-DOCS for this workspace and generate the root CLAUDE.md."
    route_to: "harness"
    why: "Scaffolding the tooling + wiki layers and the Knowledge map is the harness's job; the constitution only writes one article INTO that wiki and links one row."

  - prompt: "I'm starting from scratch and don't know where to begin — help me bootstrap the project."
    route_to: "init"
    why: "Front-door bootstrapping (gauge the user, set the accompaniment dial, recommend bundles) is init; the constitution runs after the harness exists and the profile is set."

  - prompt: "Show me how to actually configure Ruff and pytest with an 80% coverage gate in our FastAPI service."
    route_to: "fastapi"
    why: "The constitution NAMES the coverage bar; the concrete lint/test config is a stack mechanic owned by fastapi — the skill explicitly defers this."

  - prompt: "Add input validation and proper authz to our login endpoint so it can't be abused."
    route_to: "secure-coding"
    why: "Implementing the security baseline is secure-coding; the constitution only ratifies the principle (e.g. 'authn/z baseline met') and links the enforcer."

  - prompt: "Pick the type scale, color tokens, and spacing system for our app's design language."
    route_to: "design"
    why: "Choosing concrete design tokens is the design skill; the constitution at most names an accessibility floor and links wiki/stack/design.md."

# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
# the skill loaded. A skill-guided answer reconciles with the stack wiki, keeps
# principles testable, includes the fixed authorship/decisions rules, versions
# the file, and ratifies with the user — an ungrounded answer writes a vague,
# unversioned wall of aspirations.
capability:
  - scenario: "Stand up the constitution for a new project that has a Next.js frontend and a FastAPI backend. The harness already wrote 02-DOCS/wiki/stack/nextjs.md and fastapi.md with some conventions. There is a user-profile at L1 (brief)."
    must_include:
      - "Reads 02-DOCS/wiki/harness/user-profile.md and matches L1 verbosity (one line of why per principle, few questions) rather than a long interview."
      - "Runs the reconciliation pass: reads the existing wiki/stack/nextjs.md and fastapi.md, lifts only project-wide non-negotiables, and LINKS those articles instead of pasting their config; surfaces any contradiction for the user to resolve rather than auto-picking."
      - "Every principle is numbered, imperative, and testable (a number, command, or named artifact), not an aspiration like 'write clean code'."
      - "Includes the two fixed principles: git authorship is the human's (no Co-Authored-By AI / generated-with footer, enforced at ship) and significant decisions are logged."
      - "Produces a Definition of Done checklist (the merge bar verify runs against) covering format/lint, types, tests/coverage, conventions, branch+PR+authorship, security, and decisions logged."
      - "Writes 02-DOCS/wiki/sdd/constitution.md with a version (v1.0.0), ratified date, and an append-only amendment log; adds the Knowledge-map row to root CLAUDE.md additively (never deleting sections)."
      - "Shows the draft and gets explicit ratification from the user before it takes effect, and ends by pointing to the specify phase as next in the chain."

# Eval harness — `constitution` skill

Two things are checked: that the skill **triggers** on the right prompts (and
stays quiet on near-misses that belong to a sibling), and that it **measurably
improves** the constitution it produces. Cases live in `cases.yaml`. There is no
shell runner — `constitution` is a process skill judged on safety rails and
judgment, so grading is done by an **agent harness** (a Claude Code agent with
skills loaded) plus a human spot-check.

## What's in `cases.yaml`

- `should_trigger` — prompts that MUST load `constitution`.
- `should_not_trigger` — near-misses that must route elsewhere (`route_to` names
  a real sibling in this repo: `harness`, `init`, `fastapi`, `secure-coding`,
  `design`).
- `capability` — a scenario with a `must_include` rubric to grade with vs without.

## Triggering eval

Goal: the skill fires when it should and never on a near-miss.

1. Configure an agent with the **full catalog of skill descriptions** available
   for routing (constitution + its rsc-sdd phase siblings once they exist, plus
   harness, init, fastapi, nextjs, go, postgresdb, flutter, design, secure-coding,
   deployment, marketing, presentations, course-storytelling, building-agents) so
   routing competes realistically.
2. For each `should_trigger` prompt: feed it cold, record whether `constitution`
   is the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
3. For each `should_not_trigger` prompt: confirm `constitution` does NOT load and
   that the chosen skill matches `route_to`. Same 3-5 trials.
4. Score: `triggered_correctly / total_trials` across both lists.

**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
systematic false-positives** on the `harness`/`init` near-misses — those are the
known traps, since "set up the project" reads close to "set the project's
principles". A scaffolding-or-bootstrap prompt must not pull in `constitution`.

## Capability eval

Goal: prove the skill changes the answer, not just the routing.

1. For the `capability` scenario, run it **twice**:
   - **WITHOUT** the skill (base agent, no `constitution` loaded).
   - **WITH** the `constitution` skill loaded.
2. Grade each output against the `must_include` checklist — one point per
   checkable item covered. A human or grading agent marks each present / absent.
3. Compute coverage = `items_covered / total_items` for each run.

**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
lower** (target a >= 30-point gap). The discriminating behaviors are: the
reconciliation pass against `02-DOCS/wiki/stack/*` (link, don't paste), testable
numbered principles, the fixed authorship + decisions-logged principles,
versioning + amendment log, the Definition-of-Done checklist, and explicit user
ratification. A base agent typically writes a vague, unversioned wall of
aspirations that duplicates the stack wiki — score that as a capability failure
even if it reads tidy.

## Notes on honesty

- Trials are stochastic; report the raw fraction, not a rounded "pass".
- The highest-signal capability check is reconciliation: a correct answer reads
  the existing stack articles and LINKS them; it never pastes their config into
  the constitution or silently resolves a contradiction between them.
- Re-run after any edit to `SKILL.md` or `references/constitution-template.md` —
  wording changes shift both triggering and rubric coverage.
- Several `route_to` targets are rsc-sdd phase siblings (`specify`, `plan`,
  `analyze`, `sdd`) that ship alongside this skill; the near-misses here route
  only to skills already present in the repo so the eval is runnable today.

# Constitution template

Render this into `02-DOCS/wiki/sdd/constitution.md`. Keep it to 1-2 screens. Every principle is one numbered, testable statement; link the `02-DOCS/wiki/stack/*` article or the script that enforces it rather than pasting the mechanic. Strike-and-replace on amendment — never silently edit a ratified principle.

---

```markdown
---
type: constitution
title: <Project> — Constitution
description: The non-negotiable principles every rsc-sdd phase obeys.
tags: [sdd, constitution]
timestamp: YYYY-MM-DDTHH:MM:SSZ
topic: sdd
version: v1.0.0
---

# <Project> — Constitution

> Version: v1.0.0 · Ratified: YYYY-MM-DD · Last amended: YYYY-MM-DD
> The non-negotiable principles every rsc-sdd phase obeys. Stack mechanics live in
> `02-DOCS/wiki/stack/*`; this file ratifies the principle and links the detail.

## 1. Stack canon

1. Primary language(s) and runtime: <e.g. TypeScript on Node 22, Python 3.12>. Pinned in
   `<manifest>`. Detail: `02-DOCS/wiki/stack/<x>.md`.
2. Frameworks fixed: <e.g. Next.js App Router, FastAPI>. Changing one is a MAJOR amendment.
3. Package manager: <e.g. pnpm / uv>. One lockfile, committed.

## 2. Quality bar

4. Code is formatted and lint-clean on every commit (<formatter/linter>, zero warnings).
   Enforced by `<pre-commit / CI step>` — detail in `02-DOCS/wiki/stack/<x>.md`.
5. Types are <strict / checked>; the type checker passes with no errors before merge.
6. Tests gate the merge: <TDD red→green→refactor>; line coverage ≥ <N>% on changed code.
   Test tooling: `02-DOCS/wiki/stack/<x>.md`.

## 3. Conventions

7. Naming & structure: <directory layout, module boundaries, file naming>.
8. API & errors: <error shape, status codes, response envelope> where applicable.
9. Commit messages: <format, e.g. gitmoji + Conventional Commits — `✨ feat(scope): subject`>.

## 4. Branching & shipping

10. Work happens on a branch off `<default>`; merge via PR. Direct pushes to `<default>` are
    not allowed.
11. **Git authorship is the human's.** No `Co-Authored-By` an AI, no "generated with" footer.
    Enforced at the `ship` phase.

## 5. Security & privacy floor

12. No secret is ever committed. Secrets load from `01-TOOLS/<provider>/.env` (gitignored).
    Baseline: `secure-coding`.
13. <authn/z baseline, data residency, dependency policy> as applicable.

## 6. UX / accessibility floor (if there is a UI)

14. Minimum accessibility bar: <e.g. WCAG 2.2 AA, keyboard-navigable, visible focus>.
    Detail: `02-DOCS/wiki/stack/design.md`.

## 7. Performance budgets (where they matter)

15. <named budget, e.g. LCP ≤ 2.5s on the marketing site; p95 API latency ≤ 300ms>.

## 8. Knowledge & decisions

16. Every significant decision is appended to `02-DOCS/wiki/sdd/decisions.md` (date, options,
    why). The constitution is the highest-order decision record.

## Definition of Done (the merge bar `verify` runs against)

A change ships only when ALL hold:

- [ ] Formatter + linter clean (principle 4).
- [ ] Type checker passes (principle 5).
- [ ] Tests pass; coverage floor met on changed code (principle 6).
- [ ] Conventions followed (principles 7-9).
- [ ] On a branch, merged via PR, authored by the human (principles 10-11).
- [ ] No secret committed; security baseline met (principles 12-13).
- [ ] Accessibility / performance budgets met where they apply (principles 14-15).
- [ ] Significant decisions logged (principle 16).

## Amendment log (append-only)

| Date | Version | Change | Why |
|------|---------|--------|-----|
| YYYY-MM-DD | v1.0.0 | Ratified initial constitution. | Project kickoff. |
```

---

## Rendering notes

- **Drop sections that don't apply.** No UI → drop §6. No hard perf budget → drop §7. Do not pad.
- **Renumber on amendment carefully.** Prefer striking a principle (`~~10. …~~ (superseded by 17)`) and appending the new one over renumbering, so existing citations ("principle 10") stay valid.
- **Version bump rules:** MAJOR = remove/reverse a principle; MINOR = add/tighten; PATCH = wording only.
- **Link, don't paste.** Any concrete config (lint rules, pytest ini, Tailwind tokens) stays in `02-DOCS/wiki/stack/*`; the principle points to it.
- **One screen test.** If the rendered file scrolls past ~2 screens, you are documenting, not legislating — move detail to the wiki.