choice-cartographer

Surfaces implicit decisions in specs as structured choice stories for human disposition.

Updated May 24, 2026
One-click install
npx skills add https://github.com/MWest2020/skill-forge --skill choice-cartographer-mwest2020
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: choice-cartographer
Source: https://github.com/MWest2020/skill-forge/tree/main/skills/choice-cartographer
Command: npx skills add https://github.com/MWest2020/skill-forge --skill choice-cartographer-mwest2020

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Specs commit to many decisions silently, and those unrecorded choices become intent debt that teams re-litigate later. This Skill reads a specification end-to-end and emits each material choice as a Henney-style pattern story so humans can review and dispose of them before plan approval. ## Core Features & Use Cases - Six-lens decision analysis: Examines specs through forces, alternatives, defaults, patterns, consequences, and coherence lenses to surface choices the author never named. - Structured choice-story output: Writes a YAML-frontmatter record with per-story prose sections to docs/superpowers/stories/<spec-slug>.md, with dispositions left pending for human review. - Routing and validation protocol: Applies a deterministic routing rule to separate decision findings from failure findings (which belong to the diaboli reviewer), and ships a validation checklist covering frontmatter, prose structure, and cross-reference resolution. - Use Case: Before approving a design spec, dispatch this Skill to produce 5-15 choice stories naming inherited defaults, unnamed tradeoffs, and recognized patterns, then have the team mark each as accepted, revisit, or promoted. ## Quick Start Ask the agent to run the choice cartographer against your spec file and write the resulting choice-story record to docs/superpowers/stories/.

Frequently Asked Questions about choice-cartographer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I surface hidden decisions in a design spec?

Dispatch the choice cartographer against the spec file. It reads the document end-to-end, applies six lenses (forces, alternatives, defaults, patterns, consequences, coherence), and writes 5-15 choice stories to docs/superpowers/stories/<spec-slug>.md with disposition set to pending.

What is the difference between a choice story and an architecture decision record?

ADRs are written by the decision-maker to explain a known choice, while choice stories are written by an external observer to surface choices the author may not have realized they made. Both capture rationale, but only choice stories pay down intent debt from silent decisions.

How does the cartographer decide what belongs in its record versus a risk review?

It applies a deterministic routing rule: a finding belongs in the choice-story record if removing it leaves a decision unrecorded but no failure undetected. Failure-shaped findings route to the diaboli objection record, and ambiguous candidates are dropped.

Can the choice cartographer review code instead of specs?

No, this release is spec-mode only. The frontmatter mode field must be spec, and the validator fails loudly on any other value. Code-mode support is tracked as follow-up work.

What happens when a choice story has invalid cross-references?

The validator resolves objection IDs against the YAML frontmatter of the matching objections record and enforces that story references point only to earlier story IDs. Unresolvable tokens are replaced with an em-dash in place, without re-dispatching the agent.