Pre Spec Challenge

Pre-Spec Challenge

Purpose

Pressure-test candidate decisions before planning so the orchestrator learns which assumptions are still unsafe to carry forward.

When used from a project agent such as challenger-agent, let the agent own ownership, trigger rules, boundaries, and handoffs. This skill owns the challenge behavior: how to falsify assumptions, prune low-value questions, classify blocker severity, and stop once planning risk is well bounded.

This is distinct from spec-clarification-challenge: use this skill in synthesis when risk or ambiguity justifies a pre-spec pressure test; use spec-clarification-challenge inside specification as the non-trivial spec.md review-readiness gate.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Scope

• inspect candidate synthesis, not a blank request
• challenge only seams that could still change scope, correctness, ownership, failure semantics, or rollout
• convert uncertainty into the smallest actionable next step
• keep the pass compact enough that the orchestrator can reconcile it directly

Boundaries

Do not:

• make final product, architecture, API, data, security, or rollout decisions
• rewrite the whole scope or reopen already-settled decisions without concrete evidence
• ask generic category questions with no seam attached
• ask the user directly; recommend ask_user only when the orchestrator truly lacks an external fact
• produce a second design document that competes with spec.md

Escalate When

Escalate if:

• candidate synthesis is too thin to challenge meaningfully
• the real problem is missing framing rather than missing pressure-test
• one challenged point clearly needs fresh specialist research rather than more questioning
• the candidate path is so contradictory that integration or domain design must happen before challenge can help

Core Defaults

• Prefer 3-5 strong questions over broader coverage.
• Treat every question as a potential design fork: if the answer changes nothing material, drop it.
• Attack assumptions by trying to falsify them, not by asking for more prose.
• Ask about categories like security, performance, or rollout only through a concrete seam already present in the candidate synthesis.
• Stay advisory. The orchestrator decides.

Reference Files

Load references lazily. Use repository workflow docs, especially docs/spec-first-workflow.md, as the authority for phase placement; these references are compact rubrics and example banks, not exhaustive checklists or design guidance.

Load at most one reference by default. Load more than one only when the candidate synthesis spans independent decision pressures, such as both async ownership and mixed-version rollout.

| Symptom | Behavior Change | Load | | --- | --- | --- | | The input bundle may be too thin or blank-page design is tempting | Makes the model route to framing or targeted research instead of inventing challenge questions from missing decisions | references/input-sufficiency-and-challenge-readiness.md | | Candidate decisions lean on convenience assumptions like frontend dedupe, TTL cleanup, UUID secrecy, or manual fixes | Makes the model ask falsifying failure questions instead of generic "what about retries/security/scale?" prompts | references/falsifying-candidate-assumptions.md | | Source-of-truth, actor authority, side effects, async handoff, cache, or destructive admin seams are underdefined | Makes the model challenge durable ownership and recovery instead of vague ownership/auth questions or implementation advice | references/ownership-boundary-and-failure-seams.md | | Rollout, migration, compatibility, feature flags, canaries, backfills, global enablement, or rollback are material | Makes the model test mixed-version and rollback state instead of forcing ceremony or ignoring hard-to-reverse release risk | references/rollout-compatibility-and-risk-questions.md | | Strong questions exist but severity or resolution route is unclear | Makes the model classify by what changes planning and choose a concrete next action instead of overblocking or reflexively asking for more research | references/triage-and-next-action-routing.md |

Challenge Loop

1. Confirm the input is challenge-ready rather than underframed.
2. Extract the candidate assumptions that are actually carrying the plan.
3. Try to falsify each assumption by asking: what breaks if this is false in production?
4. Keep only the seams where a different answer would materially change planning.
5. Classify each surviving seam before wording the final question.
6. Stop when the unresolved set is no longer planning-critical.

Question Filter

Keep a question only if all are true:

• it names a specific challenged assumption or seam
• it changes planning, not just later polish
• it would still matter if the orchestrator already knew the general domain best practices
• it is more useful than sending the task straight back to specialist research

If any of those fail, do not ask it.

Lenses

• Input sufficiency: expect a problem frame, candidate decisions, constraints, assumptions or open questions, and evidence links that matter. If the bundle is missing, escalate instead of guessing.
• Falsification: look for assumptions disguised as convenience, policy, or v1 simplification, especially around client behavior, operator workarounds, TTLs, UUID secrecy, natural expiry, or future cleanup.
• Failure semantics: test denial, retry, timeout, duplicate request, partial success, stale state, irreversibility, and manual follow-up only when they could change planning.
• Ownership seams: challenge unclear source-of-truth ownership, actor boundaries, privilege boundaries, and cross-domain side effects that would otherwise be decided later in code.
• Rollout and compatibility: ask about migration, backward compatibility, launch cohort, canary, or rollback only when the answer can materially change implementation order or risk controls.

Blocker Classification

Use:

• blocks_planning when planning would be unsafe or misleading without resolution
• blocks_specific_domain when the question should reopen only one specialist area
• non_blocking when the point is real but can stay as explicit accepted risk or open question

Next Action Selection

Use:

• answer when the orchestrator likely already has enough evidence
• re-research when a specialist or retrieval pass should reopen
• ask_user when an external policy or product decision is missing
• defer when the point is real but can stay explicit without blocking planning
• accept_risk when the current path is still coherent and the remaining issue is a conscious trade-off

When Next Action is re-research:

• name the specialist lane or fact pattern that should be reopened
• state why local orchestrator reasoning is not enough for this seam
• say whether the orchestrator should rerun challenge after the new research returns

Stop Condition

• Stop once the remaining unresolved questions no longer change planning safety materially.
• If everything left is low-value, already tracked, or belongs in ordinary downstream design elaboration, say the checkpoint is sufficiently reconciled.

Anti-Patterns

• generic “what about security/performance?” prompting with no seam
• reopening settled scope because “more thought is always good”
• padding the pass with low-value questions to hit a quota
• drifting into architecture authorship instead of pressure-testing the candidate path
• writing commentary that explains the whole design instead of surfacing the few seams that still matter

Deliverable Shape

Return challenge work in this order:

• Challenge Summary
• Questions
• Escalations / Re-research
• Confidence

For each item in Questions, include:

• Question / Challenged Assumption
• Why It Matters
• What Changes
• Blocker Level
• Next Action
• Research Reopen when Next Action = re-research

Escalate Or Reject

• a request to nitpick rather than improve planning quality
• a challenge pass on a trivial local task with no material ambiguity
• candidate synthesis that is really a disguised blank page

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.