// Create characterization tests (Golden Master) for existing code so you can refactor or replace safely. Use before refactoring, strangler-replacing, or modifying code with unclear behavior. Captures observable behavior with a minimal harness, producing tests, fixtures, and a coverage report.
Read and write a Petri net (SDCPN) document by Automerge URL. Use when creating, editing, or querying Petri nets — adding or removing places, transitions, arcs, color types, differential equations, and parameters.
Create and maintain an Assumption Ledger — a persistent record of assumptions, their confidence, and validation status. Use when starting a new slice, resuming work in a new context window, or when implicit assumptions risk causing drift. Tracks requirements, architecture, and implementation assumptions.
Create or update a concept capsule — the conceptual anchor for a project or feature area. Use before writing code on a new project or feature, or when terms and boundaries feel unclear. Defines glossary, invariants, happy-path scenario, and non-goals.
Write a tracer-bullet card — a precise specification for one thin end-to-end slice of work. Use when scoping a new slice, defining what to build next, or breaking a feature into provable increments. Covers target behavior, boundary crossings, risks, and definition of done.
Methodology triage consultant for tracer-bullet development. Use when unsure which pragma skill to run next, when starting a new project, or when the current approach feels stuck. Interviews the user, assesses state, and recommends the next pragma skill.
Turn capsule invariants and boundary crossings into executable contracts. Use after creating a concept capsule, or when invariants need to be enforced in code. Covers preconditions, postconditions, constructor validation, domain types, and contract tests.
| name | characterize |
| description | Create characterization tests (Golden Master) for existing code so you can refactor or replace safely. Use before refactoring, strangler-replacing, or modifying code with unclear behavior. Captures observable behavior with a minimal harness, producing tests, fixtures, and a coverage report. |
| argument-hint | [subsystem / entrypoint / behavior surface to lock down] |
Create characterization tests for an existing subsystem whose behavior is unclear, messy, or AI-generated. Pin down current observable behavior so that refactoring and incremental replacement are safe.
Subsystem / entrypoint / behavior surface to lock down: $ARGUMENTS
Preconditions:
List 1-3 surfaces to lock down: public functions, CLI commands, HTTP endpoints, file-in→file-out, serialized outputs. Prefer the most stable public surface available.
Keep it small — a suite that's too big becomes unmaintainable.
Before capturing outputs, neutralize noise sources:
If behavior is inherently nondeterministic, define a tolerant comparator (ignore specific fields, assert shape/membership rather than equality).
For each fixture: run the surface, record observable output (return value / stdout+stderr / exit code / HTTP status+body), store as snapshot/golden file.
Assert: given fixture inputs → output matches golden (or tolerant comparator).
/pragma:refactor or strangler seamsCharacterization: lock down current behavior of <subsystem>
/pragma:refactor or strangler approach)State: stabilizing, Next: /pragma:refactor, Loop: /pragma:consult (default unless user explicitly continues directly)