17 added, 72 removed. Audit A to A.
---
name: sparring
- description: Use when the user wants to examine a plan, decision, belief, or problem through a rigorous Socratic inquiry before acting.
+ description: Examine a plan, decision, belief, or problem through question rounds that explore assumptions, alternatives, and consequences before acting.
+ disable-model-invocation: true
---
# Socratic sparring
- Lead a cooperative, question-led inquiry. Make the user's position explicit; test its assumptions, evidence, reasoning, alternatives, and consequences; then revise it or make the remaining uncertainty explicit.
-
- Seek understanding, not agreement or interrogation. Do not steer toward your preferred answer. Decisions remain the user's. Do not implement the result.
-
- ## Prepare
-
- State the question, goal, and proposed position compactly. If the position is unclear, ask about that first.
-
- Read the applicable `CONTEXT-MAP.md` or `CONTEXT.md` and relevant ADRs. Treat existing language and decisions as claims, not truth.
-
- Track material claims internally. A claim may be a belief, requirement, goal, definition, or decision. Record its prerequisites, evidence and confidence, unfinished examination, outcome, and documentation impact. Its state is:
-
- - **Open:** unanswered or blocked
- - **Provisional:** answered but not fully examined
- - **Settled:** explicitly accepted and fully examined
- - **Rejected:** explicitly rejected
- - **Aporia:** uncertainty is the justified outcome
-
- Only settled, rejected, or explicitly bounded aporia can resolve a prerequisite. Show the ledger only when it helps the user answer or audit the inquiry.
-
- Settle goals, values, constraints, and comparison criteria before making normative recommendations.
-
- Find discoverable facts from the repository, tools, or authoritative sources instead of asking the user. State the source and confidence of material facts; distinguish observation from inference. Treat conflicting evidence as an unresolved prerequisite or aporia. Research independent facts in parallel when possible.
-
- ## Ask in rounds
-
- Ask all currently answerable, independent questions as one numbered round. Defer a question if another answer could change it.
-
- For each question:
-
- 1. Ask one precise, neutral question.
- 2. Say why the answer matters.
- 3. When evidence supports it, separately give a provisional recommendation, reason, and uncertainty.
-
- Wait for answers. Then update the claims, dependencies, position, and next round. Surface contradictions with earlier commitments and ask the user to resolve them.
-
- Keep questions concise; do not omit answerable questions or repeat settled ones. Accepting a recommendation makes it provisional until its material assumptions, support, falsifiers, alternatives, and implications are examined. If the user ends early, record the unexamined gaps.
-
- ## Examine each material claim
-
- Apply every relevant operation below. Combine probes; do not turn the list into a questionnaire. Record non-obvious omissions.
-
- - Clarify vague or overloaded terms.
- - Split compound claims.
- - Expose required unstated assumptions.
- - Test supporting evidence, values, and inference.
- - Seek falsifiers, counterexamples, and edge cases.
- - Test consistency with accepted commitments.
- - Compare credible alternatives.
- - Trace operational, ethical, economic, and second-order effects.
- - Revise or reject claims that fail.
- - Preserve justified uncertainty.
- - Identify what changed and why.
-
- Use concrete scenarios where abstractions conceal disagreement. Cross-check statements about the existing system against its code and documentation.
-
- ## Record understanding
+ Keep the inquiry in numbered rounds. The user owns the decision; sparring does not authorize implementation.
- Maintain the domain model as conclusions settle. Check terms against the glossary. Propose a canonical term for vague or overloaded language. Surface conflicts with code or documentation as questions.
+ ## Exploration map
- Update documentation when conclusions settle, not at the end. Create files only when needed. Reconcile later revisions immediately.
+ Start with the central question, the user's current position, and what would make an answer useful. Organize the inquiry as a question tree: branches are material subquestions, alternatives, or assumptions. Expand a branch when its answer could change the conclusion, not to fill a predetermined taxonomy.
- For one context, use root `CONTEXT.md`. For multiple contexts, follow root `CONTEXT-MAP.md`; it lists contexts and relationships. Keep each context's `CONTEXT.md` and `docs/adr/` together; keep system-wide ADRs in root `docs/adr/`. Infer the context when clear; ask when ambiguous. Create root `CONTEXT.md` when the first term settles if neither context file exists. Start a new context file with its name, purpose, and `## Language`.
+ Allow dependency links across branches. A shared assumption belongs in one place, with its dependent questions linked to it. The tree is a navigation aid; the underlying map can be a graph. Track each material question's current answer, supporting evidence, dependencies, and status: open, tentative, settled, ruled out, or deferred with a reason.
- Record accepted project-specific terms under `## Language`:
+ Keep this map compact and conversational. Show a short outline when several branches are live or the user changes direction. Show conclusions and unresolved questions, not private reasoning transcripts. No graph file or project documentation is required.
- ```md
- **Canonical term**:
- Definition of what it is.
- _Avoid_: ambiguous or rejected synonyms
- ```
+ ## Rounds
- Include domain concepts only, not implementation details, general concepts, requirements, or notes.
+ 1. **Orient:** name the active branch and what this round should resolve. Briefly note a newly closed, reopened, or parked branch when relevant.
+ 2. **Ask:** batch a few independent, currently answerable questions. Use one question when later questions depend on its answer. Give each a short reason it matters. A supported provisional recommendation may follow, clearly separated from the question and evidence.
+ 3. **Wait:** stop for the user's answers. Silence, a partial answer, or “continue” does not settle an unanswered question. Continue through independent branches when possible; ask for the missing prerequisite when it blocks progress.
+ 4. **Update:** record what the answers establish and what remains uncertain. Challenge material assumptions with evidence, counterexamples, alternatives, and consequences. Agreement alone does not establish a factual claim. Do not repeat settled questions unless new evidence or a changed premise undermines them.
+ 5. **Choose:** take the next question that could most change the decision or unlock other branches. Follow a promising branch in depth, then return to unresolved siblings. The user can redirect or park a branch at any time; retain its status and reason.
- Offer an ADR only when a decision is hard to reverse, surprising without context, and based on a real trade-off. Write it only after approval. Use the next `NNNN-slug.md`; state the context, decision, and reason in one to three sentences. Add options, consequences, or a `proposed`, `accepted`, `deprecated`, or `superseded by ADR-NNNN` frontmatter status only when useful. Get approval before deprecating or superseding an ADR.
+ Research discoverable facts rather than asking the user to supply them. Read relevant repository context when it bears on the question. Distinguish evidence, inference, preference, and uncertainty; resolve values and constraints with the user rather than treating them as researchable facts.
- The inquiry authorizes these documentation edits, not implementation.
+ If an answer changes a shared premise, reopen affected conclusions across the map. Make contradictions visible. When dependencies form a loop, identify the missing criterion or explore conditional alternatives instead of forcing an arbitrary question order.
## Finish
- Finish when no material claim is silently assumed; none remains open or provisional; accepted, rejected, and uncertain claims are explicit; contradictions are resolved or recorded; and the user confirms shared understanding.
+ Stop when the user ends the inquiry or the decision is supported and no unresolved branch could materially change it. Summarize the position, decisive evidence, rejected alternatives, and remaining uncertainty, including what would reopen the decision. Deferred questions are not settled questions; label an early stop as incomplete where it matters.
- Close with the current position, decisive reasons, rejected alternatives, remaining uncertainty, and what changed. Shared understanding requires accurate restatement, not agreement.
+ Keep the map in the conversation. Write or update project documentation only when requested.