The challenge skill: risk-scaled blind-spot discovery (0.19.0, #73)

[OriNachum]

Closes #73.

What ships

/challenge — the seventh origin skill, third leg in flow order (scope → think → challenge → spec-to-plan → assign-to-workforce → deviate → summarize-delivery): a risk-scaled blind-spot discovery pass that pressure-tests a converged, exported frame before devague plan new. Method-only per the issue's stated preference — SKILL.md only, no script, no new CLI verb; the deterministic CLI is untouched (#20).

• .claude/skills/challenge/SKILL.md (t1): structured lenses, the mandatory-but-proportional rule with named escalation signals (migrations, security-sensitive work, distributed state, hardware, destructive operations, hard-to-reverse changes, concurrency hazards, data-loss surfaces), a findings-routing table over existing moves only (capture / interrogate / question / park / devague scope / devague plan risk), the after-/think-export timing with the reopen → reconverge → re-export loop, resilience-placement coaching (spec-side when it changes what, plan-side when it changes how), and a hard rule forbidding "there are no unknown unknowns" — a clean pass records examined lenses/surfaces plus residual uncertainty instead.
• devague learn teaches seven (t2): one new OPERATOR_SKILLS entry + six→seven wording in learn.py, mirrored in tests/test_cli_learn.py (TDD: 8 failing first, then green). No new subparser, module, or store.
• Seven-leg docs sweep (t3): README.md, CLAUDE.md, docs/skills.md, docs/skill-sources.md — flow tables, per-skill section, outbound origin row, don't-re-vendor list; the shipped frontmatter description is quoted verbatim, not paraphrased.
• 0.19.0 (t4): version bump, Keep-a-Changelog entry, CLAUDE.md Status paragraph.

How it was built (dogfooded end to end)

Full devague flow: /scope (5 provenance-cited scope entries) → /think (converged frame: 19 claims, 11 honesty conditions, all user-confirmed; spec at docs/specs/2026-07-15-challenge-skill.md) → a manual challenge pass over the spec itself (scope entries s6–s8 caught the hardcoded six-skill test tuple; residuals parked as v1–v2) → /spec-to-plan (4 tasks covering all 22 targets; plan at docs/plans/2026-07-15-challenge-skill.md) → /assign-to-workforce (human-approved split: t1 fable, t2–t4 sonnet; 3 waves, isolated worktrees, TDD-gated merges) → one mid-run /deviate record (d1, human-approved: t4 also writes the CLAUDE.md Status paragraph; ledger committed at .devague/deliveries/challenge-skill.json).

Evidence

• uv run pytest -n auto: 616 passed (after every wave merge).

• flake8 / black --check / isort --check / markdownlint-cli2 on changed files: clean.

• Open items (recorded, not hidden): guildmaster re-vendor happens on its own schedule (follow_up); proportionality calibration is observable only across future dogfooded passes (unknown_nonblocking).

• devague (Claude)

[qodo-code-review]

PR Summary by Qodo

Add /challenge origin skill and bump devague to 0.19.0

✨ Enhancement 📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Add method-only /challenge skill for risk-scaled blind-spot discovery between /think and
 /spec-to-plan.
• Teach /challenge via devague learn and update tests for seven-skill output.
• Update docs and release metadata for seven-leg flow; bump version to 0.19.0.

Diagram

graph TD
  O["Operator / agent"] --> C["/challenge SKILL.md"] --> M["Existing devague moves"] --> S[("Frame state / exports")]
  O --> L["devague learn"] --> C
  D["Docs (flow tables)"] --> C
  R["Release metadata"] --> D
  S --> E["Exported spec.md"]
  subgraph Legend
    direction LR
    _p["Process / doc"] ~~~ _s[("State / artifact")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a first-class `devague challenge` CLI verb

• ➕ Structured/consistent output and storage for findings without relying on conventions
• ➕ Could enforce proportionality and required clean-pass records mechanically
• ➕ Easier to integrate into tooling (JSON output, automation hooks)
• ➖ Violates the stated constraint to avoid new engine/verbs for now (Expose plan dependency waves as deterministic metadata, not orchestration #20 / issue preference)
• ➖ Higher maintenance surface and more risk of orchestration creeping into the deterministic CLI

2. Bake challenge into `devague plan new` as a pre-flight gate

• ➕ Prevents skipping the pass; guarantees it happens before planning
• ➕ Can standardize what “done” means for challenge prior to seeding a plan
• ➖ Turns an operator method into enforced CLI workflow, which may be premature
• ➖ Harder to keep the CLI non-orchestrating; increases coupling between spec and plan commands

3. Use a lightweight checklist template in docs (no skill)

• ➕ Even smaller surface area than a new skill; minimal maintenance
• ➕ Avoids changes to learn/tests and flow tables
• ➖ Less discoverable and less consistently applied than an operator skill
• ➖ Weaker integration with the “route findings through existing moves” rule

Recommendation: Keep the current method-only /challenge skill approach. It matches the repo’s “deterministic CLI, operator-driven method” boundary, delivers the new capability with minimal runtime risk, and still leaves room to evolve into a first-class CLI verb later if repeated dogfooding shows the workflow needs stronger enforcement or structure.

Files changed (15) +1209 / -55

Enhancement (2) +318 / -14

SKILL.mdAdd method-only /challenge skill definition and operating procedure +290/-0

Add method-only /challenge skill definition and operating procedure

• Introduces the new seventh origin operator skill '/challenge' as a risk-scaled blind-spot discovery pass run after '/think' export and before '/spec-to-plan'. Defines proportionality/escalation signals, structured lenses, a routing table mapping findings to existing devague moves, and hard rules (notably forbidding “no unknown unknowns” conclusions).

.claude/skills/challenge/SKILL.md

learn.pyTeach seven operator skills; add challenge as method-only +28/-14

Teach seven operator skills; add challenge as method-only

• Extends 'OPERATOR_SKILLS' with a new 'challenge' entry in workflow order and updates teaching text from six skills to seven. Keeps behavior limited to learn/authoring content (no new subparser/engine), and marks challenge as method-only (no resolver script).

devague/cli/_commands/learn.py

Tests (1) +4 / -2

test_cli_learn.pyUpdate learn tests for seven skills and method-only challenge +4/-2

Update learn tests for seven skills and method-only challenge

• Extends the skill-name tuples to include 'challenge' and marks it as method-only. Updates parametrized cases so 'devague learn skills:challenge' is covered and the learn surfaces stay consistent with the updated teaching content.

tests/test_cli_learn.py

Documentation (7) +262 / -37

CHANGELOG.mdAdd 0.19.0 release entry for /challenge and seven-leg updates +19/-0

Add 0.19.0 release entry for /challenge and seven-leg updates

• Introduces a Keep-a-Changelog entry for 0.19.0 describing the new '/challenge' skill and the learn/docs updates that move the project from six legs to seven.

CHANGELOG.md

CLAUDE.mdDocument /challenge in Status and update flow references to seven legs +37/-18

Document /challenge in Status and update flow references to seven legs

• Adds a new 0.19.0 Status paragraph announcing '/challenge' and its constraints (method-only, no new CLI verb/engine). Updates narrative sections to reference the seven-leg operator flow and include 'challenge' in the devague-origin skill list.

CLAUDE.md

README.mdUpdate operator-skill flow to include /challenge and method-only constraints +10/-7

Update operator-skill flow to include /challenge and method-only constraints

• Updates the overview of agent-driven operation to reflect the seven-leg flow, adding '/challenge' between '/think' and '/spec-to-plan', and clarifying it is method-only with findings routed through existing moves.

README.md

2026-07-15-challenge-skill.mdAdd human-readable build plan markdown for challenge-skill +51/-0

Add human-readable build plan markdown for challenge-skill

• Adds a markdown export of the plan describing tasks, acceptance criteria, dependencies, and risks for delivering the /challenge skill and related doc/learn/release changes.

docs/plans/2026-07-15-challenge-skill.md

skill-sources.mdAdd /challenge to outbound origin skills and do-not-re-vendor list +15/-11

Add /challenge to outbound origin skills and do-not-re-vendor list

• Updates origin-skill description text and tables to include 'challenge' as devague-authored and re-broadcast by guildmaster. Adds a new table row for the challenge skill and updates guidance not to re-vendor devague-origin skills.

docs/skill-sources.md

skills.mdUpdate flow table to seven legs and add a /challenge skill section +43/-1

Update flow table to seven legs and add a /challenge skill section

• Updates the operator-skills flow table to include 'challenge' and adds a dedicated section quoting the shipped SKILL.md description verbatim. Clarifies behavior/constraints: method-only, uses existing moves, and not a new gate.

docs/skills.md

2026-07-15-challenge-skill.mdAdd exported spec for the challenge-skill change +87/-0

Add exported spec for the challenge-skill change

• Adds the dated exported spec documenting audience, before/after rationale, requirements, boundaries, decisions, and follow-ups for shipping '/challenge' as a method-only skill.

docs/specs/2026-07-15-challenge-skill.md

Other (5) +625 / -2

current_planPoint devague working state to the new challenge-skill plan +1/-1

Point devague working state to the new challenge-skill plan

• Updates the current plan slug to 'challenge-skill', reflecting the active exported plan in devague state.

.devague/current_plan

challenge-skill.jsonRecord an approved deviation for the delivery +20/-0

Record an approved deviation for the delivery

• Adds a delivery record capturing deviation d1: including a 0.19.0 Status paragraph in CLAUDE.md as part of the version bump task.

.devague/deliveries/challenge-skill.json

challenge-skill.jsonAdd exported frame describing the /challenge skill change +377/-0

Add exported frame describing the /challenge skill change

• Adds the exported devague frame documenting goals, boundaries (no new CLI verb/engine), decisions (timing, resilience placement, escalation signals), and scope exploration for the /challenge skill work.

.devague/frames/challenge-skill.json

challenge-skill.jsonAdd exported plan with tasks for skill, learn/tests, docs, and release +226/-0

Add exported plan with tasks for skill, learn/tests, docs, and release

• Adds the exported plan specifying four tasks (t1–t4) with acceptance criteria and risks, covering the skill authoring, learn/test updates, documentation sweep, and the 0.19.0 release bump.

.devague/plans/challenge-skill.json

pyproject.tomlBump project version to 0.19.0 +1/-1

Bump project version to 0.19.0

• Updates the package version from 0.18.1 to 0.19.0 to reflect the new skill release.

pyproject.toml

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review