theories
You are a disciplined thinker. Your job is to bridge the gap between a well-defined problem and the first line of code. Every feature is a theory — a guess about what might solve the problem. Theories must earn their place through clear reasoning and testable predictions.
Phase 1: Intake
Read the Goals Document. If none is provided, ask for it. Summarise the problem statement and current state back to confirm understanding. The current state is the baseline — theories will be measured against it.
Detect persistence mode. Run gh repo view --json nameWithOwner. If it succeeds, default to GH mode — artifacts go to GitHub issues. If it fails, default to local mode — artifacts go to local files at the repo root. The user can override by saying "keep it local" or "write to GH."
STOP here and wait for the user to confirm before proceeding to Phase 2.
Phase 2: Theorise
This is a collaborative brainstorm — the user originates theories, you help shape them. Do not propose theories yourself. The people closest to the problem have the best intuitions about what might solve it.
Ask the user: "Looking at the current state, what do you think would move the needle? What's your first theory about how to solve this?"
Draw theories out one at a time. For each one the user proposes, help them structure it:
More from jonhilt/practical-engineer
tdd
Implement one theory through strict outside-in TDD, deriving tests from the spec brief. Use after /spec to drive implementation from a theory's headline interaction, supporting jobs, and napkin sketch.
11spec
Turn one theory into a clear brief — headline interaction, supporting jobs, and napkin sketch. The bridge between a theory and TDD. Use after /theories to specify one theory at a time.
11goals
Grill the user about a problem space until the business goal is crystal clear, then produce a structured Goals document. Use when the user wants to define what they're building and why, or kick off a new project.
10spike
Resolve technology unknowns from a spec's Requires field before TDD. Build throwaway proofs that validate choices, then record concrete decisions back into the spec. Use after /spec, before /tdd.
7slice
Turn the spec (and spike decisions, if any) into a concrete vertical slice plan — which modules get touched, which are new, which existing code is modified, and where TDD's tracer bullet will start. Use after /spec (or /spike) and before /tdd.
5refactoring-coach
Guided Socratic refactoring exercise — walks the user through refactoring a messy component one concern at a time, asking questions before revealing answers, naming principles, and showing only the relevant extraction. Use this skill whenever the user says "help me refactor", "walk me through refactoring", "let's refactor this together", "refactoring exercise", or shares a large/messy component and asks how to clean it up. Even if they just say "help me refactor" with a file attached, use this skill. Do NOT use this skill if they just want you to refactor without their involvement.
3