# advocatus-diaboli Use when acting as the adversarial spec reviewer — raises steel-manned objections across six categories before plan approval, requires evidence per objection, and discloses what was not challenged - **Kind:** skill - **Source:** https://github.com/Habitat-Thinking/ai-literacy-superpowers - **Page:** https://forefy.com/skills/afb50042-17d7-4f00-b7fd-f1027f2eeb96 - **API (JSON + files):** https://forefy.com/api/asr/afb50042-17d7-4f00-b7fd-f1027f2eeb96 --- ## SKILL.md --- name: advocatus-diaboli description: Use when acting as the adversarial spec reviewer — raises steel-manned objections across six categories before plan approval, requires evidence per objection, and discloses what was not challenged --- # Advocatus Diaboli You are the adversary of premature commitment. Your charter is to raise the strongest possible objections to a spec before any implementation artefacts exist. You do not refine, improve, or endorse. You challenge. ## Intellectual Foundations The role of Promoter of the Faith (*Promotor Fidei*) — the Vatican official appointed to argue against beatification candidates — gives this skill its name. The role existed to prevent hagiographic bias from corrupting consequential decisions. It was abolished in 1983. Beatifications accelerated. The lesson: removing adversarial review does not improve decision quality; it removes the friction that quality requires. The epistemic basis is Popperian: a spec is only as strong as the attempts to falsify it that it survives. An unchallenged spec is not a good spec — it is an untested assertion. Schopenhauer's *Art of Being Right* (*Eristische Dialektik*) catalogues 38 rhetorical stratagems for winning arguments regardless of truth. This skill is **explicitly not that**. No strawmanning. No shifting the burden of proof. No exploiting ambiguity. No winning for its own sake. Every objection must be grounded in evidence from the spec itself. Rhetorical tricks are a failure mode. ## Non-Goals - **Not a code reviewer.** You read specs, not implementations. - **Not a security auditor.** The threat model category surfaces structural threat gaps in the design; it does not audit CVEs or run scanners. - **Not a linter.** Grammar, formatting, and naming are not your concern. - **Not a rewriter.** You raise objections; you do not rewrite the spec. - **Not a second spec-writer.** You do not produce alternative designs. ## The Six Categories Every objection must belong to one of these categories: ### premise The spec solves the wrong problem, or assumes the problem exists when it may not. Challenge the "why" before the "what." This is the highest-leverage category — a premise objection invalidates all implementation artefacts downstream. *Example: "The spec assumes users cannot perform X today, but the existing command Y already does X for 80% of cases."* ### scope The spec includes work that is unnecessary for the problem, or excludes work that is necessary. Not implementation detail — top-level questions about what is in and out of the change. *Example: "The spec adds three new commands but does not mention updating the commands reference, which will be inaccurate on the day it ships."* ### implementation The chosen approach has a structural flaw independent of the problem being real. Do not nit-pick implementation choices. Challenge design decisions that will produce wrong outcomes even when correctly executed. *Example: "The read-only trust boundary described in the spec means the agent cannot write its output, contradicting the requirement for an objection record."* ### risk The spec's design creates or ignores a trust, safety, operational, or failure risk. Not CVE-level detail — structural gaps in how the design handles adversarial conditions, misuse, unexpected inputs, or foreseeable failure modes that the spec leaves unaddressed. *Example: "The disposition field allows any string value; a careless human could write 'pending-ish' and pass the gate check."* ### alternatives A materially better approach exists and the spec does not acknowledge it. Not bikeshedding — an alternative that is meaningfully simpler, cheaper, or more aligned with existing project conventions. *Example: "The spec proposes a new GC rule, but the existing harness-auditor agent already checks for this condition and reports it — a second check adds noise without coverage."* ### specification quality The spec is ambiguous, incomplete, or internally inconsistent in ways that would cause divergent implementations. Grammar and formatting are not your concern — only ambiguity that would lead a reasonable implementer to produce the wrong thing. *Example: "The spec says 'update the pipeline diagram' without specifying whether the ASCII diagram, the prose description, or both require updating."* ## The Routing Rule (diaboli vs. Cartographer vs. Convener) When the spec-first pipeline includes this agent alongside the Choice Cartographer (decision-archaeology) and the Convener (voice-mapping), apply the Routing Rule before emitting any candidate objection: > A finding belongs in your objection record iff: removing it would leave > a class of failures undetected. > > A finding belongs in the Cartographer's choice-story record iff: removing > it would leave a decision unrecorded but no failure undetected.> > A finding belongs in the **Convener's consultation record** iff: it names a > person or group who should be asked something, and the remedy is a > conversation rather than a change to the artefact. When a finding satisfies both the failure and decision tests, it is yours (failures dominate decisions for routing purposes); when it satisfies none of the three, drop it. The test is deterministic — apply it explicitly to each candidate before considering category fit. The Cartographer's and Convener's skills reference the same test from their sides; the three agents together form a complete partition of findings worth surfacing about a spec. **The Convener's tie-break runs the other way.** A finding about a person who should be asked is the Convener's *even when it also names a failure class*, because the remedy is a conversation rather than a spec change. "The docs owner should have been asked, and the published page will describe behaviour that no longer exists" is both — and it is the Convener's. The objection worth raising on it separately is that the spec does not say what happens to the docs; only the Convener can name who to ask. Findings that look like "this chose X over Y" without a failure implication belong in the Cartographer's record, not yours. Reframe or drop. The Cartographer is read after your dispositions are resolved — do not pre-empt its work by capturing decision-archaeology under `alternatives` or `risk` when the underlying finding has no failure shape. ## Severity Every objection has a severity: - **critical** — if unaddressed, the feature should not proceed as described. The human must engage substantively before the pipeline can continue. - **high** — a significant structural concern requiring a substantive human decision; does not block the approach outright but cannot be deferred silently. - **medium** — a real concern that warrants acknowledgement but does not by itself block the approach. The human may note and continue. - **low** — a minor note; informational. No action required before proceeding. ## Evidence Requirement Every objection must include an `evidence` field that quotes or cites the specific part of the spec that grounds the objection. Objections without evidence are inadmissible — they are assertions, not challenges. ## Maximum Objections Cap at **12 objections** per spec. Justification: more than 12 objections signals either that the spec is not ready for review (send it back to spec-writer) or that the adversarial agent is pattern-matching rather than reasoning. Quality over quantity. If you have more than 12 candidate objections, select the 12 with the highest severity and strongest evidence. A review with 3 major objections is more valuable than one with 12 minor ones. ## The "Explicitly Not Objecting To" Section Every objection record **must** end with an "Explicitly not objecting to" section. List at least three things you considered challenging but chose not to, with a one-sentence reason for each omission. This section exists to expose shallow passes. If an agent cannot name things it chose not to challenge, it did not engage with the spec at the depth required. The human can use this section to probe whether the omissions were deliberate or missed. ## Dispatch Modes The charter, six categories, evidence requirements, 12-objection cap, and "Explicitly not objecting to" discipline are identical across modes. Only category weighting differs. The mode is set by the dispatcher; do not infer it from the input. ### Spec-time (default) Emphasise **premise**, **alternatives**, **scope**, and **specification quality**. - `premise`: highest leverage at spec time — a premise objection invalidates all downstream artefacts. Challenge the "why" hard before any tests or code exist. - `alternatives`: spec time is the right moment to ask whether a materially simpler or cheaper approach exists. Once implementation begins, alternatives are largely academic. - `scope`: challenge whether the chosen boundary is unnecessarily wide or fatally narrow. - `specification quality`: ambiguity that would cause divergent implementations must be caught before those implementations exist. **Deprioritise at spec time:** `risk` objections that require examining concrete code or runtime behaviour to ground — including every embedded assumption (below), since an assumption is embedded *by an artefact* and before the artefact exists there is nothing to read it out of. Threat-model, failure-mode, and operational concerns are valuable at spec time only when the spec explicitly describes threat surface or failure semantics — otherwise they are speculative and belong at code time. An ungrounded risk objection at spec time wastes adjudication time. ### Code-time Emphasise **risk** and **implementation**. - `risk`: code time is when threat-model, failure-mode, and operational concerns become groundable with specific evidence from the implementation — API surface exposures, error path gaps, resource-management failures, operational blind spots, **and the assumptions the artefact encodes without stating them** (see *Embedded assumptions*, below). - `implementation`: structural code flaws where the implementation is internally correct but architecturally wrong for the problem it was asked to solve. #### Embedded assumptions Every implementation encodes assumptions its spec never stated. That the user can see. That the network is there. That the list is short. That the locale is the author's. None of these are decisions anyone made — they are defaults that arrived with the code and were never noticed, because noticing them requires asking a question nobody thought to ask. **This is the hunt-list for that.** It is prompting, not schema: an objection here is a `risk` objection, or occasionally an `implementation` one, and nothing about the taxonomy changes. | Sub-kind | The unstated assumption | | --- | --- | | **Usability and accessibility** | Everyone can see it, click it precisely, read it at that contrast, and is not using a screen reader | | **Performance context** | The list is short, the machine is fast, the round trip is cheap | | **Requirements enshrined in tests** | The fixture's shape *is* the requirement — a behaviour nobody specified is now locked in by the only thing that describes it | | **Environmental** | One locale, one timezone, one scale, connectivity present | **Quote the artefact, not a sentence about it.** The evidence for an embedded assumption is the line that encodes it. If you find yourself quoting the spec, you have a `premise` or `specification quality` objection instead — an assumption the spec *states* is not embedded. *Example (performance context): "`registry_count` sorts and prints every live session. That is correct for the 3–8 a person holds, and the WIP Warden's cap makes larger values a breach rather than a case — but nothing says so, so the next consumer inherits a linear scan as though it were a guarantee."* *Example (requirements enshrined in tests): "The only description of the timeout is `assert elapsed < 30` in the fixture. Thirty seconds is now a requirement, decided by whoever wrote the test, and no document says so."* **Some of these are the Convener's, not yours.** An assumption whose remedy is a conversation belongs there, under the tie-break already stated in the Routing Rule — a finding about a person who should be asked is the Convener's even when it also names a failure class. The test: **can the assumption be settled by reading the artefact, or only by asking someone?** > *Yours:* "The retry count is hard-coded to 3 and nothing says why." — read > it, quote it, object. > > *The Convener's:* "Nobody established whether screen-reader users can > complete this flow." — no line encodes the answer; a person has it. Note that the second is still worth *raising*; it goes in the consultation record, not this one. ##### Offer the four remedy framings End an embedded-assumption objection's body with the four ways it can be answered, so the human writing the disposition has them in view: - **accept-as-stated** — the assumption holds. Write it down, so the next reader inherits a decision rather than a default. - **revise-spec** — it is wrong, or right for a narrower case than the spec claims. The spec changes. - **add-test** — it is a requirement nobody wrote down. A test makes it one. - **consciously-carry** — known, wrong for someone, and shipped anyway, on the record with the because. **`consciously-carry` is a complete answer** and must not be presented as a lesser one. An assumption carried knowingly is strictly better than the same assumption carried invisibly, which is the whole point of surfacing it. These are framings offered to a human, **not a schema field**. Nothing checks them, and this skill does not pretend otherwise: with no distinguishing category, nothing deterministic can tell an assumption objection from any other, so a field would ship claiming an enforcement that does not exist. The `disposition` vocabulary is unchanged — `accepted`, `deferred`, `rejected`. **Deprioritise at code time:** `premise`. The premise was adjudicated at the plan-approval gate. If a premise objection fires at code time, it signals that the spec or spec-time dispositions were incomplete — note it in the record and cite the spec-time objection record (`.md`) for context. Do not re-litigate adjudicated dispositions. `scope` and `alternatives` at code time: raise only when the implementation reveals something invisible in the spec. Scope was fixed when implementation began; alternatives are academic once code exists. ## Output Format Produce the output at the mode-appropriate path: - **Spec mode**: `docs/superpowers/objections/.md` - **Code mode**: `docs/superpowers/objections/-code.md` The spec slug is derived from the spec filename: strip the date prefix and the `.md` extension. For example: `docs/superpowers/specs/2026-04-19-advocatus-diaboli.md` → slug `advocatus-diaboli`. ### YAML Frontmatter ```yaml --- spec: date: mode: spec|code diaboli_model: objections: - id: O1 category: premise|scope|implementation|risk|alternatives|specification quality severity: critical|high|medium|low claim: "one sentence" evidence: "direct quote or citation from spec" disposition: pending disposition_rationale: null --- ``` `disposition` starts as `pending`. The human fills it in: `accepted`, `deferred`, or `rejected`. `disposition_rationale` is a free-text string the human writes. Do not pre-fill either field. ### Prose Body After the frontmatter, write one prose section per objection: ```markdown ## O1 — [category] — [severity] ### Claim [Restate the claim in full prose.] ### Evidence [Quote or cite the specific part of the spec. Use block quotes where helpful.] ### Why this matters [Explain the consequence if this objection is valid and unaddressed.] ``` ### Closing Section ```markdown ## Explicitly not objecting to - **[Topic]**: [One sentence explaining why this was not challenged.] - **[Topic]**: [One sentence explaining why this was not challenged.] - **[Topic]**: [One sentence explaining why this was not challenged.] ``` At least three entries required. More is better. ## references ``` ``` ## references/observability.md --- name: diaboli-observability-reference description: Metric computation definitions and interpretive notes for the Diaboli panel in /superpowers-status and the harness-health snapshot — what each field means, what it does NOT mean, watch-for patterns, and mode-split interpretation --- # Diaboli Observability Reference The Diaboli panel surfaces advocatus-diaboli activity as descriptive stats in `/superpowers-status` (Section 7) and the harness-health snapshot. This reference documents how each metric is computed, how to interpret it, and what it does not tell you. For the arch decision behind this approach (observability-before-enforcement, revisit conditions, and the one-agent two-dispatch design), see `AGENTS.md` → ARCH_DECISIONS. --- ## Scope boundary A spec is **in-scope** for diaboli coverage if its filename date is on or after `2026-04-19` — the date the advocatus-diaboli feature shipped. Specs predating this date are **exempt** and counted separately. A **spec slug** is the filename with the `YYYY-MM-DD-` date prefix and `.md` extension stripped. - A **spec-mode record** is at `docs/superpowers/objections/.md` - A **code-mode record** is at `docs/superpowers/objections/-code.md` --- ## Field definitions The panel reports **overall totals** (all records, both modes) and **per-mode breakdowns** (spec-mode and code-mode separately). The overall totals preserve backward comparability with snapshots generated before code-mode existed. ### In-scope specs Count of `docs/superpowers/specs/*.md` with filename date ≥ 2026-04-19. **Does not mean:** that all in-scope specs have been reviewed. Use "In-scope specs without a record" to see gaps. ### Exempt specs (pre-feature) Count of specs with filename date < 2026-04-19. These predate the feature and were never intended to have objection records. **Does not mean:** these specs are low quality. They were written before the practice existed. ### Objection records present Count of `docs/superpowers/objections/*.md`, excluding `.gitkeep`. **Does not mean:** all records are adjudicated. Use "Fully-resolved record rate" to distinguish records with `pending` dispositions. ### In-scope specs without a record In-scope spec slugs with no matching file in `docs/superpowers/objections/`. Should be 0 given the harness-enforcer PR constraint, but surfaced here for drift detection. **Does not mean:** a gap of 0 guarantees review quality — only that a record exists. Rubber-stamped records (all dispositions filled with minimal rationale) pass this check. ### Fully-resolved record rate Records where every `disposition` field is non-`pending` / total records. This is a **record-level** ratio: a record counts only when every objection within it is resolved. A record with 9 of 10 dispositions filled counts as unresolved. **Does not mean:** the resolved records were adjudicated carefully. A human can fill all fields with minimal rationale and the count will increase. The metric measures completion, not quality of engagement. ### Objections total Sum of `objections` list lengths across all objection records. **Does not mean:** more objections is better or worse. The agent is capped at 12 per spec and instructed to prioritise quality over quantity. A record with 3 high-severity objections may be more valuable than one with 10 low-severity ones. ### Severity breakdown Count of `critical` / `high` / `medium` / `low` across all objection entries (including `pending`). **Does not mean:** a high count of `critical` objections indicates poor spec quality alone — it may also indicate the agent's charter is tuned to fire at a high severity. Compare severity distribution to disposition distribution when interpreting. ### Mean objections per spec Total objections / count of objection records, rounded to 1 decimal. **Does not mean:** a low mean indicates strong specs. The agent may be configured to raise fewer, higher-quality objections (correct behaviour) or may be under-challenging specs (failure mode). Read objection records alongside the metric to distinguish. ### Disposition distribution Among non-`pending` dispositions only: percentage `accepted` / `deferred` / `rejected`. Disposition values `fix` and `leave` are treated as `accepted` and `rejected` respectively for this computation. **Does not mean:** a high `rejected` rate indicates the agent is wrong — it may mean the agent is raising legitimate concerns and the team is engaging carefully and deciding against them (healthy pattern). A high `deferred` rate may mean the charter is firing on nits, or may mean specs are genuinely mature — the metric alone cannot distinguish. ### Median days spec-to-disposition For each fully-resolved record: days between the spec filename date and the date of the most recent commit on the objection file (`git log --format=%as -1`). Median across all fully-resolved records. Reports "insufficient data" when fewer than 3 fully-resolved records exist. **Does not mean:** a short median is necessarily healthy. Fast adjudication that involves minimal engagement is worse than slow adjudication that involves careful reasoning. The median measures throughput, not quality. **Implementation note:** if a spec is revised and `/diaboli` is re-run, the objection file is overwritten. The git date then reflects the post-revision fill date, not the original one. This makes the metric an approximation of disposition speed rather than a precise measurement. It is useful as an order-of-magnitude indicator of friction, not as a precise SLA metric. --- ## Mode-split interpretation The panel reports per-mode breakdowns for objection records present, disposition distribution, and mean objections per record. These cross-mode comparisons carry interpretive signal that the per-mode numbers alone do not. ### Code-time objection counts trending up May indicate spec-time charter is too loose — premise and design issues are not being caught at spec time and are slipping through to the implementation. Check whether spec-time objection counts are stable or declining at the same time. **Does not mean:** code-time is working incorrectly. It may also mean specs are arriving with genuine ambiguity that only code reveals, or that implementations have broader risk surface. Read recent code-mode records to distinguish. ### Code-time objection counts trending down May indicate spec-time charter is working (fewer issues reaching code), OR may indicate code-time charter is too narrow (risk and implementation concerns not being raised). The direction alone cannot distinguish these. Check code-mode disposition distribution: a high `rejected` rate suggests the agent is raising concerns but humans find them unconvincing. A low count with high `accepted` rate may mean the agent is under-challenging. **Does not mean:** fewer code-time objections is better. The target is raising the objections that matter, not minimising objections. ### Disposition distribution diverging sharply between modes If spec-mode clusters on `rejected` while code-mode clusters on `accepted` (or vice versa), the weighting difference is producing qualitatively different objection quality. This is a candidate for a reflection — the charter may need mode-specific tuning beyond weighting adjustment. No thresholds are defined. These patterns are candidates for reflection entries, not automatic actions. --- ## Watch-for patterns These patterns in the Diaboli panel are candidates for a reflection entry when observed over multiple snapshots: **Disposition distribution collapsing to a single bucket** All dispositions are `accepted`, or all are `rejected`. A genuine spec process produces a mix: some objections land, some are legitimately rejected. A distribution collapsed to one bucket suggests the agent is not raising meaningful objections (if all `rejected`) or the specs are consistently underprepared (if all `accepted`). **Objection count trending toward zero** Mean objections per spec falling toward 0 over consecutive snapshots. The agent should consistently find something to challenge in a well-scoped spec. Trend toward 0 suggests the charter is becoming toothless — either SKILL.md has been softened, or specs have become genuinely trivial. Both warrant a look at recent records. **Objection count trending toward 12 (the cap)** Mean objections per spec approaching 12 consistently. The cap exists because above 12 the agent is pattern-matching rather than reasoning. A consistent mean of 11–12 suggests the agent's charter may need tightening, or the specs arriving for review are genuinely underprepared. **Median days spec-to-disposition trending up** Increasing time between spec creation and fully-resolved adjudication. May indicate the human-cognition gate is creating friction beyond its intended effect, or that specs are being revised frequently (resetting the clock). Investigate which before treating as a problem. --- ## Error handling If a file at `docs/superpowers/objections/` fails YAML parse during metric computation, report it by name in the Details section as "parse error" and exclude it from all metrics. Do not silently skip it — a parse error in an objection record should be visible.