pi-dev-team 0.2.0

package/skills/specs/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: specs
+description: Collaborative workflow for producing the three specification artifacts (intent, architecture notes, acceptance criteria) that describe a change and its goals before any implementation begins. Its value is resolving ambiguity with a human before build starts — not synthesizing edge cases. Use when starting any new feature or behavior change — do not write code until artifacts pass the consistency gate. BDD/Gherkin scenarios are authored later, per slice, in /plan.
+role: orchestrator
+user-invocable: true
+---
+
+# Agent-Assisted Specification
+
+<!-- pi-port-notes -->
+## pi port notes (read first)
+
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.
+<!-- pi-port-notes -->
+
+
+Role: orchestrator. This command produces specification artifacts and gates
+progression to `/plan` — it does not write implementation code, author
+per-slice Gherkin scenarios, or begin building.
+
+## Positioning — what this skill is for
+
+This skill's value is **resolving ambiguity with a human before build begins**
+(Rec 1, `docs/experiments/RECOMMENDATIONS.md`). No downstream workflow recovers
+information the spec never stated — under vague specs every workflow arm scored
+0% on acceptance tests probing an omitted decision. The Ambiguity Resolution
+Protocol below is the mechanism: it forces every gap to be either resolved by a
+human or documented as inferable before implementation starts.
+
+What this skill is **not** for: edge-case synthesis. Run to completion, the
+full `/specs`→`/plan`→`/build` pipeline's explicit acceptance-criteria
+synthesis does not out-perform TDD's failing-test discipline at surfacing
+unstated edge cases (25% vs. 33% pooled EDGE pass — Experiment 03, reported in
+`docs/experiments/02-final-results.md`). The two have different failure modes
+and both are worth keeping: `/specs` catches ambiguity a human must resolve;
+the build cadence's per-behavior tests catch edge cases the spec implies but
+never enumerates.
+
+## Step 0 — Select the mode
+
+`/specs` runs in one of two modes, chosen from the **shape of the argument** —
+there is no flag, so every existing `/specs "<description>"` invocation is
+unaffected. Announce the selected mode and why before any work begins.
+
+| Argument | Mode |
+|---|---|
+| Resolves to a readable `.md`/`.txt`/`.pdf`, or a fetchable GitHub issue URL | **validate** — critique a document we did not write |
+| *Looks* like a path or issue URL (a path separator, one of those extensions, or a GitHub issue URL shape) but does not resolve or cannot be fetched | **refuse** — see below |
+| Resembles neither | **authoring** — today's collaboration loop, unchanged |
+
+**A path-like argument that does not resolve is never reinterpreted as prose.**
+Silently feeding a mistyped path into the authoring loop turns a typo into a
+spec seeded from the literal path string, which the author may not notice for
+a long time. Refuse instead, naming the unresolved path or the fetch failure
+(private, deleted, unauthenticated, network).
+
+**Unsupported formats are refused too, never partially parsed.** The supported
+set is what `Read` handles natively. `.docx` is explicitly out — the plugin
+ships stdlib-only Python (ADR 0014/0015) and no stdlib path parses it. Name the
+reason and the conversion to perform; do not guess at a partial read.
+
+Validate mode then runs the same critique categories, Ambiguity Resolution
+Protocol, and Consistency Gate as authoring mode, against the source text
+rather than a co-authored draft — a third-party document blocks exactly as hard
+as an in-house draft. **Every extracted acceptance criterion cites the source
+passage it came from; one with no citable passage is an inference and is logged
+as such, never presented as if the source stated it.** Load
+[`references/extraction.md`](references/extraction.md) for the supported
+inputs, the citation rule, and the routing.
+
+## Step 1 — Existing-spec version check
+
+Before drafting or updating a spec, check whether a spec file already exists for
+this feature:
+
+- If no spec file exists: proceed directly to the collaboration loop below.
+- If a spec file exists: read its opening lines and check for a `<!-- spec-version: -->` comment or a `**Format:**` header field.
+  - If the marker is absent or predates the current skill version (see frontmatter `version:`): surface this to the user — *"An existing spec was found but appears to use an older format. Regenerate from scratch, or confirm you want to update in place?"* — and wait for explicit direction before proceeding.
+  - If the marker matches the current version: proceed to the collaboration loop below with the existing file as base.
+
+This prevents silently overwriting a current spec and catches format drift before
+the plan phase consumes stale artifacts.
+Produce three specification artifacts collaboratively with the human before any implementation begins. The spec describes the change and its goals; it does **not** define Gherkin scenarios — those are authored per slice during `/plan`. The consistency gate is a hard stop; do not proceed to planning until it passes.
+
+## Rules
+
+1. **No implementation during specification.** No code, no tests, no infrastructure until the consistency gate passes.
+2. **One feature per specification.** A spec describes a single coherent change end-to-end. Vertical slicing is deferred to `/plan` — do not slice here. Split into separate specs only when the request bundles genuinely unrelated features (see Scope Split Protocol).
+3. **Consistency gate is a hard stop.** Conflicts caught now cost minutes; conflicts caught during implementation cost sessions.
+4. **Behavior contracts are authored in the plan.** The spec sets intent, architecture constraints, and acceptance criteria. `/plan` turns those into per-slice Gherkin scenarios — the single source of truth for expected behavior. No implementation without a scenario; no scenario without an acceptance test.
+5. **Max 2 critique-refine iterations** per artifact. If it doesn't stabilize, escalate to the Orchestrator.
+6. **Preserve human language** when refining. The human owns the specification; the agent improves precision.
+7. **Structured critique output.** Categorize every critique (gap, ambiguity, conflict, scope violation) with a specific reference to the artifact text.
+8. **Document decisions, not just outcomes.** When the human rejects an agent suggestion, note why — prevents the same suggestion from recurring.
+
+## Artifacts
+
+| Artifact | Purpose | Format |
+| --- | --- | --- |
+| Intent Description | What the change achieves and why | Plain language, 1–3 paragraphs |
+| Architecture Specification | Where the change fits and what constraints apply | Structured notes: components, interfaces, dependencies, constraints |
+| Acceptance Criteria | Observable outcomes and quality thresholds that define "done" | Measurable criteria with pass/fail conditions |
+
+Observable user behavior is captured as Gherkin in `/plan`, one scenario set per slice. The spec's job is to make that authoring unambiguous, not to pre-write it.
+
+## Collaboration loop
+
+Every artifact follows the same loop:
+
+1. **Human drafts** based on current understanding.
+2. **Agent critiques** — categorize each finding as gap, ambiguity, conflict, or scope violation, with a specific reference.
+3. **Human decides** — accept, reject, or modify.
+4. **Agent refines** — produce an updated version incorporating decisions.
+
+Repeat up to **2 iterations** before escalating.
+
+### Critique categories
+
+| Category | Description |
+| --- | --- |
+| Gaps | Missing acceptance criteria, unstated assumptions, undefined behavior |
+| Ambiguities | Statements two implementers would interpret differently |
+| Conflicts | Contradictions between artifacts or with existing system behavior |
+| Scope violations | Spec bundles unrelated features that belong in separate specs |
+
+## Ambiguity Resolution Protocol
+
+After critiquing the artifacts but before writing the final acceptance criteria, run this protocol on every gap and ambiguity finding. This is a hard step — it cannot be skipped.
+
+For each gap or ambiguity:
+
+**Step A — Attempt inference.** Look for a reliable basis: existing codebase behavior, domain conventions, similar precedents in the system, or unambiguous implication from stated requirements.
+
+**Step A2 — Predictability check.** Generate **at most one** plausible
+alternative outcome per criterion and test it against the source; if the source
+does not rule it out, classify `requires-stakeholder-input`. Record the outcome
+in the Ambiguity Log row every time, pass included. Load
+[`references/predictability-check.md`](references/predictability-check.md) — it
+covers absurd-candidate rejection, the no-plausible-alternative case, and why
+this does not duplicate `plan-review-acceptance`.
+
+**Step B — Classify the finding.**
+
+| Class | Meaning | Action |
+|-------|---------|--------|
+| `inferable` | A reasonable developer, given the codebase and domain, would make the same choice | Document the inference and its rationale; proceed |
+| `requires-stakeholder-input` | The decision depends on product or business intent not evident from context; two reasonable developers would choose differently | **Block — ask the human before proceeding** |
+
+**Step C — Resolve `requires-stakeholder-input` items.** Collect all such items and present them as a single batch to the human before writing acceptance criteria:
+
+> "Before writing acceptance criteria, I need clarification on N decisions the spec leaves open: [list]"
+
+Wait for answers. Only then finalize the criteria.
+
+**What "inferable" is NOT:** a convenient default. Naturalness or simplicity does not make a decision inferable — the test is whether a developer working from context alone would reliably land on the same answer. If in doubt, classify as `requires-stakeholder-input`.
+
+**Record every classification** in an `## Ambiguity Log` section of the spec file (see Output below). This log is the audit trail that turns "we asked before building" from an assertion into an artifact.
+
+This protocol exists because the most common failure mode of spec synthesis from a vague prompt is writing decisions that look thorough while encoding the same happy-path assumptions a direct implementation would make silently. The log prevents that by making every assumption visible and every gap either resolved by the human or documented as inferable with explicit rationale.
+
+## Gap classification: NO_REFACTOR / REFACTOR_REQUIRED / LOW_VALUE
+
+When a critique surfaces a missing-test or coverage gap, classify it so the spec only carries work that delivers signal:
+
+- `NO_REFACTOR` — a meaningful test can be written against the code as it stands. Carry it into the acceptance criteria.
+- `REFACTOR_REQUIRED` — production code needs a testability change before a meaningful test is possible. Note the change.
+- `LOW_VALUE` — **skip, not defer.** A `LOW_VALUE` finding is never written into the acceptance criteria and is never parked as deferred backlog; deferring it only re-surfaces the same no-signal work later. All three criteria must hold: no branching logic, no observable outcome (the only possible assertion is that a mock was called), and a higher-layer test already covers the path.
+
+`LOW_VALUE` is the one class dropped rather than tracked — the Ambiguity Log records the skip and its rationale, nothing more. It never becomes an acceptance criterion and never reaches `/plan` as work.
+
+## Scope signals
+
+A specification bundles too much when any of these fire:
+
+- Specification effort exceeds a short conversation.
+- More than ~5 components are affected.
+- Genuinely unrelated features are described (not just multiple slices of one feature).
+- The features described would not ship or be validated together.
+
+Note: a single feature that decomposes into several deliverable increments is **normal and expected** — that decomposition happens in `/plan`, not here. Only split the spec when the features are independent.
+
+### Scope Split Protocol
+
+1. Identify the unrelated features bundled into the request.
+2. Propose a split into separate specs, one per feature.
+3. Human approves the split before specification continues on any feature.
+4. Each feature gets its own full set of three artifacts.
+
+## Glossary
+
+Capture domain terms **while drafting** Intent and Acceptance Criteria. A
+definition the agent inferred starts `unverified`; `verified` requires a human.
+A term still `unverified` at the end of the loop is a gap finding and routes
+through the Ambiguity Resolution Protocol — it does not block the Consistency
+Gate by itself. Load [`references/glossary.md`](references/glossary.md) for the
+status contract, the resolution rule, and the downstream consumers.
+
+## Completeness sweep
+
+After the critique loop and **before** the Consistency Gate, sweep for what the
+spec never mentioned. A spec that says nothing about deletion produces no
+criterion to find incomplete — the omission is the absence of a criterion, and
+absence is invisible to every per-criterion check we run.
+
+Load [`references/completeness-checklist.md`](references/completeness-checklist.md)
+and apply it: CRUD per named entity, plus authentication, authorization,
+audit/logging, and error handling for the spec as a whole.
+
+Report the entities you enumerated, group findings by entity, and route each
+unaddressed cell into the Ambiguity Log as `inferable` (with rationale —
+including "read-only by design") or `requires-stakeholder-input`. A cell that
+does not apply is recorded with its reason, never dropped. The reference states
+why each of those is required.
+
+**The sweep is not a gate.** It blocks only through the existing Ambiguity
+Resolution Protocol; it introduces no new gate, severity scheme, or confidence
+score. It also never grades a criterion that already exists — that is
+`plan-review-acceptance`'s scope. The two answer different questions: "is there
+a criterion here at all?" versus "is this criterion complete?"
+
+## Cross-Artifact Consistency Gate
+
+Validate all three artifacts as a set:
+
+- [ ] Intent is unambiguous — two developers would interpret it the same way.
+- [ ] Every behavior or goal in the intent maps to at least one acceptance criterion.
+- [ ] Architecture specification constrains implementation to what the intent requires, without over-engineering.
+- [ ] Same concepts are named consistently across all three artifacts.
+- [ ] No artifact contradicts another.
+- [ ] Every gap and ambiguity finding is logged — either documented as `inferable` (with explicit rationale) or resolved via explicit stakeholder input. No finding is left as an undocumented assumption.
+
+**Hard stop**: do not proceed to planning until every item passes. The ambiguity log item is the most critical: a passing gate with undocumented assumptions produces false confidence.
+
+## Output
+
+Three artifacts (Intent, Architecture Specification, Acceptance Criteria) plus a
+consistency gate pass/fail verdict. Be concise — flag gaps and conflicts; do not
+narrate the collaboration process.
+
+Once the gate passes, persist the artifacts and trigger the next phase. That
+procedure — classifying file vs. GitHub-issue persistence, the body template,
+and the `/plan` auto-trigger — lives in
+[`references/persistence.md`](references/persistence.md). **Load it now.**

package/skills/specs/references/completeness-checklist.md

@@ -0,0 +1,83 @@
+# Completeness checklist
+
+Loaded on demand by [`../SKILL.md`](../SKILL.md)'s completeness sweep, which
+runs after the critique loop and before the Cross-Artifact Consistency Gate.
+
+## What this checklist is for
+
+`plan-review-acceptance` already checks whether each criterion a spec
+*contains* is complete — boundaries at zero/one/many, an error path per happy
+path, negative criteria, illegal state transitions. This checklist answers a
+different question.
+
+A spec that never mentions deletion produces **no criterion** for that agent to
+find incomplete. The omission is not a weak criterion; it is the absence of one,
+and absence is invisible to every per-criterion check. The same holds for
+authorization, audit, and error handling when a spec simply never raises them.
+
+**This checklist never grades a criterion that exists.** It reports cells with
+no corresponding criterion at all. Judging the quality of one that is present
+stays `plan-review-acceptance`'s scope, and that boundary is deliberate — the
+two agents answer "is there a criterion here at all?" and "is this criterion
+complete?" respectively.
+
+## This checklist is fixed
+
+One shipped list, not extensible per project. A per-project override is a
+hypothetical requirement with no current caller; building it now would be
+speculative design.
+
+## CRUD, per named entity
+
+For every entity the spec names, check all four:
+
+| Operation | Ask |
+|---|---|
+| **Create** | How does one come into existence? Who may create it? What makes a creation invalid? |
+| **Read** | Who may see it? Is any field restricted? What does a miss return? |
+| **Update** | Which fields are mutable? What transitions are illegal? Is concurrent update addressed? |
+| **Delete** | Can one be deleted? Soft or hard? What happens to things referencing it? |
+
+A spec may legitimately have no answer for a cell — a read-only projection has
+no create, update, or delete. That is an `inferable` finding **with its
+rationale recorded**, never a silently dropped cell.
+
+## Cross-cutting concerns
+
+Check the spec as a whole against all four:
+
+| Concern | Ask |
+|---|---|
+| **Authentication** | Who is the actor, and how is that established? |
+| **Authorization** | Which actors may do which of the operations above? |
+| **Audit / logging** | What must be recorded, and is any of it required rather than nice to have? |
+| **Error handling** | What does the system do when a dependency fails, not just when input is invalid? |
+
+## Domain-implied surfaces
+
+Beyond the fixed cells above, check the administrative and non-functional
+surfaces the spec's own domain implies — an operator's view, a retention or
+export obligation, a throughput or latency expectation the domain takes for
+granted. These are domain-specific by nature, so they are a prompt to look, not
+a fixed list to tick.
+
+## Reporting
+
+**Say which entities were enumerated.** Extracting entities from prose is a
+model step, not a parser's; showing the list is what lets a human catch one
+that was missed. Without it, a missed entity is indistinguishable from an
+entity with no findings.
+
+**Group findings by entity**, and separate cells dispositionable in one answer
+("nothing in this spec is ever deleted — confirm intentional?") from those
+needing individual judgment. A flat dump of CRUD × every entity plus four
+concerns is a wall of questions that invites rubber-stamping, which defeats the
+sweep.
+
+## Routing
+
+Each unaddressed cell becomes an Ambiguity Log entry, classified `inferable`
+(with rationale) or `requires-stakeholder-input`. **The sweep is not itself a
+gate** — it blocks only through the existing Ambiguity Resolution Protocol,
+exactly as every other finding does. No new gate, no new severity scheme, no
+confidence score.

package/skills/specs/references/extraction.md

@@ -0,0 +1,58 @@
+# Extracting a spec from a document someone else wrote
+
+Loaded on demand by [`../SKILL.md`](../SKILL.md) when Step 0 selects **validate
+mode**. Authoring mode never reads this file.
+
+## Why extraction needs its own rules
+
+In authoring mode the human drafts and we critique, so the first artifact any
+gate sees is one they wrote. In validate mode the source already exists and we
+did not help write it: whoever is driving reads it, forms a mental model, and
+writes criteria from that model. By the time a gate runs, every ambiguity the
+source contained has already been resolved — correctly or not — and the
+criteria read cleanly *because* someone picked an interpretation.
+
+The citation rule below is what keeps that resolution visible instead of
+invisible.
+
+## Supported inputs
+
+| Input | Handling |
+|---|---|
+| `.md`, `.txt`, `.pdf` | Read natively |
+| A GitHub issue URL | Fetch the issue body |
+| `.docx` and anything else `Read` cannot handle | **Refuse**, naming the reason and the conversion to perform |
+
+Never attempt a partial parse of an unsupported format. A half-read
+requirements document produces a spec that looks complete and is not.
+
+## What to extract
+
+Populate the same three artifacts authoring mode produces — Intent Description,
+Architecture Specification, Acceptance Criteria — from the source's content,
+plus the usual Ambiguity Log.
+
+## The citation rule
+
+**Every extracted acceptance criterion carries a citation** to the passage it
+came from: a section heading, a line reference, or a short verbatim quote.
+
+**A criterion with no citable passage is an inference, not an extraction**, and
+is recorded in the Ambiguity Log as one. It is never presented as though the
+source stated it.
+
+Without this, extraction and inference are indistinguishable in the output —
+which is the exact failure this mode exists to prevent. A reader of the
+resulting spec must be able to tell "the RFP says this" from "we concluded
+this", because only the second kind needs checking with a stakeholder.
+
+## Routing
+
+Findings enter the **existing** Ambiguity Resolution Protocol and the existing
+Ambiguity Log, classified `inferable` (with rationale) or
+`requires-stakeholder-input` (a hard block). No new gate, no new severity
+scheme, no confidence score.
+
+A third-party document blocks exactly as hard as an in-house draft. It contains
+*more* unresolved ambiguity, not less — weakening the bar here would invert the
+protocol's whole purpose.

package/skills/specs/references/glossary.md

@@ -0,0 +1,59 @@
+# The spec glossary
+
+Loaded on demand by [`../SKILL.md`](../SKILL.md) when domain terms need
+capturing. The persisted shape lives in
+[`persistence.md`](persistence.md)'s body template.
+
+## Why a glossary at spec time
+
+`ubiquitous-language` enforces terminology consistency, but only once terms are
+already in use. Nothing captured, at spec time, which domain terms were still
+undefined — so a term nobody had agreed on reached `/plan` looking like an
+ordinary word, and the disagreement surfaced later as a naming argument or, far
+worse, as two components meaning different things by "order".
+
+## When terms are captured
+
+**While drafting Intent and Acceptance Criteria**, not as a separate pass. Terms
+surface naturally there; a separate pass would re-read the same artifacts to
+find the same words.
+
+## The two statuses
+
+| Status | Meaning |
+|---|---|
+| `verified` | A **human** confirmed this definition during the collaboration loop |
+| `unverified` | The agent inferred it, or nobody has confirmed it yet |
+
+There is no third state. "Proposed" or "disputed" would need their own routing
+rules and have no consumer.
+
+**`verified` requires a human.** An agent confirming its own inferred definition
+is exactly the "looks thorough while encoding a happy-path assumption" failure
+the Ambiguity Resolution Protocol exists to prevent — if an agent could
+self-verify, the status would carry no information at all.
+
+## Routing, and what it does not do
+
+A term still `unverified` at the end of the loop is a gap finding and enters the
+existing Ambiguity Resolution Protocol, classified `inferable` (the definition
+follows unambiguously from codebase or domain convention) or
+`requires-stakeholder-input` (two reasonable people would define it
+differently).
+
+**An unverified term does not block the Consistency Gate by itself.** It blocks
+only if the protocol classifies it as blocking. Blocking on every unverified
+term would make specs painful enough that people route around `/specs` entirely
+— which costs more than the ambiguity it would catch.
+
+**When a human later confirms a term**, its row flips to `verified` **and** its
+Ambiguity Log entry is resolved. A term cannot be `verified` while its own
+finding stays open; leaving the entry dangling would make the log's audit trail
+lie about what is still outstanding.
+
+## Downstream
+
+The glossary is persisted inside the spec artifact, so `ubiquitous-language` and
+`domain-review` consume it by reading the spec they already locate. No separate
+file, no index, no new lookup mechanism — and no new gate, severity scheme, or
+confidence score.

package/skills/specs/references/persistence.md

@@ -0,0 +1,115 @@
+# Persisting spec artifacts
+
+Loaded on demand by [`../SKILL.md`](../SKILL.md) once the Cross-Artifact
+Consistency Gate passes. Nothing above that gate refers into this file.
+
+After the gate passes, persist all three artifacts plus the verdict so downstream commands (`/plan`, `/build`, spec-compliance-review) can find the spec — chat-only specs are lost between sessions. **Where** they're persisted depends on the project's origin and whether it has opted into the issue-first specs convention.
+
+## Classify where to persist
+
+1. Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/git_origin_host.py` to classify the origin remote: `github` / `other` / `none`.
+2. When the result is `github`, additionally run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/specs_convention_marker.py` to classify the project's root `CLAUDE.md`: `marker` (contains the issue-first-specs opt-in phrase, e.g. "Specs and plans are GitHub issues here, not files") / `no-marker` (file exists, phrase absent) / `none` (no root `CLAUDE.md` found). If it reports `no-marker` or `none`, you MAY still read the root `CLAUDE.md` yourself and apply judgment for an equivalently-worded-but-differently-phrased declaration of the same convention before concluding "no marker" — but this manual-judgment fallback is deliberately unverified by any automated test, unlike the script's literal-match path (see the script's own module docstring).
+3. **Branch**:
+   - `github` origin **and** a marker found (by the script or by manual judgment) → **Persist to GitHub issue** (below). No downstream consumer of the shipped plugin is silently switched to this path — it requires both an actual GitHub origin and an explicit, repo-declared opt-in.
+   - Anything else — non-`github` origin, `none` origin, or a `github` origin with **no** marker found by either path — → **Persist to file** (below). This is today's behavior, unchanged.
+
+## Persist to file
+
+1. **Slugify** the feature name: lowercase, replace spaces with hyphens, strip special characters. ("User Login with MFA" → `user-login-with-mfa`)
+2. **Create** `docs/specs/` if missing.
+3. **Check** whether `docs/specs/<slug>.md` already exists. If yes, ask: overwrite or create a versioned file (`<slug>-v2.md`)?
+4. **Write** using this structure:
+
+```markdown
+# Spec: <Feature Name>
+
+## Intent Description
+<intent artifact>
+
+## Architecture Specification
+<architecture artifact>
+
+## Acceptance Criteria
+<acceptance criteria artifact>
+
+## Glossary
+
+Domain terms this spec depends on. `verified` means a **human** confirmed the
+definition during the collaboration loop — not that an agent found a plausible
+one. Render the section even when there is nothing to define.
+
+| Term | Definition | Status | Source |
+|------|------------|--------|--------|
+| <term> | <definition> | `verified` / `unverified` | <where the definition came from> |
+
+## Ambiguity Log
+
+All gap and ambiguity findings from the Ambiguity Resolution Protocol, with their classifications and rationale.
+
+| Decision | Classification | Resolved By | Rationale / Answer |
+|----------|---------------|-------------|-------------------|
+| <decision text> | `inferable` / `requires-stakeholder-input` | inference / human | <rationale or human's answer> |
+
+## Consistency Gate
+- [x/  ] Intent is unambiguous
+- [x/  ] Every behavior/goal maps to an acceptance criterion
+- [x/  ] Architecture constrains without over-engineering
+- [x/  ] Terminology consistent across artifacts
+- [x/  ] No contradictions between artifacts
+- [x/  ] Every gap/ambiguity finding is logged — inferable with rationale or resolved by human
+```
+
+1. **Print** the file path to chat so the user can find it.
+
+## Persist to GitHub issue
+
+**Issue titles are Conventional Commits, not `Spec: <Feature Name>`.** These
+issues become epics — their titles seed branch names, PR titles, and (once
+their sub-issues land) release versions, so they must pass the same
+commitlint ruleset as a commit message (`.github/workflows/issue-title-lint.yml`
+enforces this after the fact by labeling `needs-conventional-title`; do not
+rely on that backstop — lint proactively, before `gh issue create`, so the
+label is never needed). Compose the title as `<type>(spec): <Feature Name>`
+— `type` is almost always `feat` (a spec describing new behavior) or `docs`
+(a spec that is itself the only deliverable, no code follows); pick
+whichever matches the work the spec actually describes, never default
+blindly to one. Example: `feat(spec): User Login with MFA`. Verify with
+`printf '%s' "<composed title>" | npx commitlint --verbose` before creating
+or renaming — if it exits non-zero, fix the title, don't create anyway.
+
+1. **Slugify** the feature name (same rule as above) — used to derive the search query, not a file path or the title itself.
+2. **Search** for an existing open issue: `gh issue list --search "<Feature Name> in:title" --state open`. If this call itself exits non-zero, treat it as a hard failure — **never** as "zero matches" (that would risk silently creating a duplicate issue) — report the failure and its cause to chat, and fall back to **Persist to file** above with the already-composed content so the approved spec is never lost.
+3. **Branch on the match count**:
+   - **Zero matches** → proceed straight to create (step 4).
+   - **Exactly one match** → interactive: ask "Found existing issue #N for this spec — update it in place, or create a new one?"; non-interactive (no usable TTY): default to **updating** that single match in place (never create a duplicate) and log the auto-choice.
+   - **Two or more matches** → interactive: surface every matching issue and ask which to update, or whether to create a new one instead — never silently pick one; non-interactive: default to **creating** a new issue and explicitly log the ambiguity (which candidate issues it did not act on).
+4. **Compose** the issue body using the same structure as the file template above — **cite it, never copy it**: there is exactly one body template in this file, and a second one would be a drift source rather than a mirror (Intent Description, Architecture Specification, Acceptance Criteria, Glossary, Ambiguity Log, Consistency Gate), titled `<type>(spec): <Feature Name>` per the rule above.
+5. **Create** (`gh issue create --title "<type>(spec): <Feature Name>" --body "<composed body>"`) or **update** (`gh issue edit <N> --body "<composed body>"`) per step 3's decision. Updating an existing issue's body never touches its title — if the existing title predates this convention, rename it too (`gh issue edit <N> --title "..."`) rather than leaving a stale non-conventional title behind.
+6. If the create/update call exits non-zero, report the failure and its cause to chat, do **not** claim success, and fall back to **Persist to file** above with the already-composed content.
+7. On success, **print** the resulting issue URL to chat — do not write `docs/specs/<slug>.md` on this path.
+
+## Auto-trigger /plan
+
+**Authoring mode only.** The two modes end differently, and deliberately so:
+
+| Mode | Terminal behavior |
+|---|---|
+| **authoring** | Auto-invoke `/plan`. Do not ask first — the approved spec is the trigger. |
+| **validate** | Print the persisted location **and a reason clause**, then offer `/plan` as an explicit next step. Never auto-invoke. |
+
+The auto-trigger's "do not ask first" contract is justified by the human having
+just co-authored and approved the spec. Validating a third-party RFP, a vendor
+brief, or a competitor's document carries no such commitment — auto-planning it
+could be actively wrong, so validate mode stops.
+
+The printed message must name that reason, not just make the offer: a user who
+has only ever seen authoring mode will otherwise read the stop as a regression.
+Something like *"not auto-invoking /plan: this document wasn't co-authored and
+approved with you — run /plan when you're ready."*
+
+In authoring mode, after persisting, automatically invoke `/plan` with the feature description. The plan command discovers the spec artifacts, decomposes the feature into vertical slices, and authors the Gherkin scenarios for each slice.
+
+**Key this off which persistence action actually succeeded, not the "Classify where to persist" decision** — the GitHub-issue path can itself fall back to file (search failure at step 2, or create/update failure at step 6):
+
+- **A file was written** (either "Classify where to persist" chose the file path, or the GitHub-issue path fell back to one): invoke `/plan "<feature description>"` — `/plan` discovers `docs/specs/**` on its own.
+- **An issue was created or updated** (step 7 succeeded): invoke `/plan "<feature description>" --spec-issue <issue-url>`, passing that issue's URL. Without this, `/plan`'s own Step 1 (which only searches `docs/specs/**`) would immediately hit its "no specification artifacts found" prompt in the very same run — reintroducing the human interruption this auto-trigger's "do not ask first" contract exists to avoid.

package/skills/specs/references/predictability-check.md

@@ -0,0 +1,77 @@
+# The predictability check
+
+Loaded on demand by [`../SKILL.md`](../SKILL.md)'s Ambiguity Resolution
+Protocol. It runs **between Step A (attempt inference) and Step B (classify)**
+— it is a test applied *during* classification, not a separate pass over the
+artifacts.
+
+## The failure mode it attacks
+
+The protocol names its own weakness plainly: spec synthesis tends to produce
+"decisions that look thorough while encoding the same happy-path assumptions a
+direct implementation would make silently." `inferable` is where that failure
+lands. An assumption gets waved through because it reads as natural — and
+naturalness is explicitly *not* the test.
+
+## The test
+
+For each acceptance criterion, generate **at most one** candidate alternative
+outcome — a behavior a reasonable developer might implement instead — and check
+whether the spec text rules it out.
+
+- **The source does not rule it out** → `requires-stakeholder-input`, not
+  `inferable`.
+- **The source rules it out** → stays `inferable`, and the check is recorded as
+  passed.
+
+### At most one, evaluated — not always one, manufactured
+
+The check is a tripwire, not an enumeration. Generating several alternatives per
+criterion would turn a classification aid into its own analysis phase and
+inflate the Ambiguity Log past readability.
+
+"At most one" is deliberate wording. When a criterion is unambiguous enough that
+every candidate alternative would be absurd, the check records that **no
+plausible alternative exists** and passes. It does not manufacture a bad one to
+satisfy a quota — that would produce exactly the false blocks the next section
+rejects.
+
+### Plausible, not absurd
+
+DeFOSPAM's equivalent floats deliberately absurd alternatives to provoke
+stakeholder correction. That works in an advisory tool whose findings are
+suggestions. Here the output flips a **blocking** classification, so an absurd
+alternative manufactures a false block — and false blocks are how a gate gets
+ignored. The alternative must be one a competent developer could actually ship.
+
+## Recording
+
+**Every outcome is recorded in the Ambiguity Log row, including a pass.**
+
+| Outcome | Recorded as |
+|---|---|
+| Flipped to `requires-stakeholder-input` | The generated alternative, in the row's rationale — it is the question the human is being asked |
+| Stayed `inferable` | The check, marked passed, with the alternative the source ruled out |
+| No plausible alternative existed | The check, marked passed, noting that |
+
+An omitted check is indistinguishable from a skipped one. The log is the audit
+trail that makes "we asked before building" an artifact rather than an
+assertion, so a silent pass would hollow it out.
+
+## Division of labor with `plan-review-acceptance`
+
+That agent already applies binary verifiability — "can two people independently
+check this criterion and agree on pass/fail?" — at `blocker` severity, and it
+still owns weasel-word detection and per-criterion completeness. This check does
+not duplicate it.
+
+**What differs is placement, and placement is the whole point.**
+`plan-review-acceptance` runs one stage later, against criteria **we** authored.
+Checking our own restatement for predictability cannot catch a source
+requirement that was unpredictable *before* we normalised it: by then the
+ambiguity is already resolved, and the criterion reads cleanly precisely because
+someone picked an interpretation. The earlier placement sees the source text;
+the later one structurally cannot.
+
+No new gate, severity scheme, or confidence score — the check only moves items
+between the two existing classifications.