SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdiscovery

discovery

Design & creation

View repository

Updated 10-15 17:29

About this skill

/discovery - Dense Discovery Phase Adapter

Absorbed skills (ag-s43tg)

brainstorm (goal-vs-implementation clarification) + design (product-fit pressure test) — trigger detail in the Folded-In section below.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Constraints

  • Delegate research and plan separately; delegate premortem only for MVP-slice mode because the fanout duel is already its premortem verdict.
  • Prove a capability is absent before scoping new construction to prevent duplicate machinery and false net-new estimates.
  • Route only fanout/one-way-door decisions through the duel; keep routine MVP slices inside the bounded quick path.
  • After three MVP premortem failures, run exactly one bounded plan-pawl helper round; resume on UNSTUCK and ask the human only on ESCALATE.

Loop position: move 1 (shape intent as BDD) plus the seed for move 3 (slice candidates) of the operating loop. Discovery turns a goal plus delegated child artifacts into one dense execution packet for /crank and /validate. It is also the re-plan engine for /rpi's Agile Re-Plan Loop: after the initial plan, it runs only from an explicit orchestrator re-plan request carrying a cited Learn plan-impact packet. Seed slice candidates small: one Given/When/Then behavior each, refactor candidates kept separate from feature candidates — small batches + refactor-after-green are the load-bearing quality moves, not test-first ordering (Finster 2026, skills/standards/references/agentic-workflow-evidence.md); binding decomposition discipline is /plan (PR-010/PR-011).

Folded-In Trigger Surface (brainstorm, design)

Discovery is the fold target for the retired standalone brainstorm and design skills (skill-prune phase 2). Fire /discovery for their use-cases:

  • Brainstorm — Separate goals from implementation. Clarify goals before planning: separate WHAT from HOW, explore the problem space before committing to a solution, and capture Given/When/Then acceptance examples. The full intent → Gherkin → executed-red → bead-DAG contract is owned by behavior-first-planning — cite it when the beads must carry runnable done-criteria. Open-ended ideation (generate-winnow, --ideate) is the Open-Ended Path below.
  • Design — Validate product fit before discovery. Use when framing a problem, checking product/market fit, or pressure-testing user value before writing a discovery packet or any code. The product-validation gate (PRODUCT.md alignment, council --preset=product) runs as discovery's conditional design delegation step.

Strict Delegation Contract (default)

Discovery runs brainstorm and design as internal modes (absorbed, ag-s43tg) and delegates to /research, /plan, and /premortem as separate skill invocations. Strict delegation is the default.

Anti-pattern to reject: inlining /research work (grep + read + synthesize), collapsing /plan into an inline decomposition, skipping /premortem. See ../shared/references/strict-delegation-contract.md for the full contract, supported compression escapes (--quick, --skip-brainstorm, --interactive/--auto, --no-scaffold), and the Premortem Anti-Rationalization Clause (what does NOT count as a premortem: an inline risk section you wrote, a prior adversarial pass on an input/premise rather than this plan, or "a related council already ran").

Re-baseline before you scope (mandatory for "improve X" / "build the missing Y"): /research MUST confirm a capability doesn't already exist before scoping new construction. The --auto trap is author-as-researcher scoping "what's unbuilt" from memory without grepping — existing machinery gets re-estimated as net-new. Every "X is missing" claim carries the search that proved it; no search → /premortem's re-baseline check (2.4–2.8) WARN/FAILs it. Run that existence search as ms search "<capability phrase>" first (fast path when ms is available — command -v ms, or the mcp__ms__search tool is attached; else grep skills/**/SKILL.md + docs/SKILLS.md) and cite the hits in the packet's overlap/prior-art section.

See references/isolation-contract.md for the mechanical four-lever model and the compression patterns flagged by scripts/check-skill-isolation.sh. See references/best-practices.md for the lifecycle principle + anti-pattern citation table.

Narrow Waist

Discovery does not carry raw child-skill output forward. It records artifact paths, verdicts, the hexagon: boundary block from docs/architecture/intent-to-loop-hexagon.md, and the six Context Density Rule fields:

Field Meaning
intent Behavior or capability to produce
boundary Bounded context, non-goals, write scope
evidence Acceptance examples, tests, gates, verdicts
decision Why this plan shape was chosen
constraint Safety, runtime, token, and process limits
next_action Exact /crank or follow-up command

Everything else stays in child artifacts and is linked by path.

Discovery To Plan Port

Use the Skill Ports and Adapters vocabulary and the Intent-to-Loop Hexagon for the boundary between Discovery and Plan:

Boundary piece Discovery contract
Inbound port shape_intent from operator goal or BDD intent
Outbound port plan_slices into /plan
Driving adapter /discovery skill invocation
Driven adapter /plan skill invocation plus br/file persistence
Context packet density block, artifact links, acceptance examples, non-goals, constraints
Guard adapter plan-pawl duel verdict (fanout) or /premortem verdict (MVP-slice) before packet handoff

Executable acceptance: references/discovery.feature — Discovery hands dense intent across the plan_slices port (promoted from inline; soc-qk4b.2).

Goal-design packet inputs (intent.md + driver.md) use references/goal-design-packet-input.md: run the checker before research; failure blocks; checked packets feed density fields and candidate slice seeds, not a /plan replacement.

Plan-Pawl Duel Gate

Risk-class routing: MVP vertical slice vs fanout (decide FIRST)

The duel is for one-way doors, not every slice. Route first:

  • Fanout class (architecture forks, one-way-door decisions, cross-agent coordination contracts, product decisions): run the plan-pawl duel below — the multi-model pawl over the PLAN artifact (docs/contracts/pawls.md). It SUBSUMES the old single-judge Codex fanout approval AND the /premortem council into one cross-family gate (--duel, auto-on for fanout/--complexity=full).
  • MVP vertical slice (default for routine runtime/CLI work): skip the duel (--no-duel). Run the discovery DAG under a hard time-box — ~15 min discovery, ~90 min slice — then stop; the slice gets only the inline --quick premortem. Work surfaced mid-slice becomes follow-up beads, never absorbed into the active bead.

The plan-pawl gates plan SHAPE, never behavior: the 2026-06-12 runtime review found a coherent fanout+approval set that still missed an auth bypass one adversarial test would have caught (learning).

The gate (fanout-class work only)

Insert the duel before /plan creates beads. The two-judge ApprovalEdge shape is docs/contracts/codex-fanout-approval-packet.md; the DAG step is STEP 3.5 in references/dag.md.

  1. Write at least three independent PerspectivePlan artifacts with different lenses (product/user value, architecture/gate integrity, operations/migration).
  2. Winnow those into one SynthesisPacket (selected plan, rejected alternatives, rationale, open questions, risks).
  3. Run the cross-family DUEL: two distinct-family judge panes (e.g. Claude + Codex via agent-native with ntm, --no-user, fresh-context by construction) each write one judge verdict to .agents/duel/<run-id>/.
  4. Decide deterministically — never read the panes yourself: ao plan-pawl decide --dir .agents/duel/<run-id> --round <N> --max-rounds <duel-rounds>. exit 0 PASS (quorum: no FAIL, >=2 distinct families) -> /plan; exit 3 REDO -> auto-redo (a FAIL re-synthesizes; a mechanical WARN auto-applies + re-judges; a judgment WARN is surfaced, non-blocking); exit 4 BLOCKED -> breaker tripped (round > max / judgment flag / oscillation), stop (the andon).
  5. Persist a duel ApprovalEdge (both judge panes, the duel_verdict_dir, the decision). For fanout this verdict IS the premortem verdict — do not run a second council.

Approval evidence must survive the worktree: before the gated bead/epic closes, mirror the council/duel artifacts (or a compact proof packet) to a tracked durable surface (see codex-exec) — .agents/ in a temp worktree is ignored.

Open-Ended Path (generate-winnow → operationalize → refine)

Additive to the default flow — it does not replace the strict-delegation contract or the artifact-first DAG. This path activates for open-ended "improve the project"-style goals ("improve the project", "what should we build next", "make X more robust") OR when --ideate is passed. For a specific goal, the default flow (brainstorm-clarify → research → plan → premortem) is unchanged.

On the open-ended path, Discovery prepends the generate-winnow methodology before research/plan and adds two steps after planning. Full detail lives in references/bead-operationalization.md and references/ideation-mode.md.

  1. Ideate (delegate to brainstorm --ideate). Invoke brainstorm in ideation mode (a real skill invocation — strict delegation still applies; do NOT inline the 30-idea generation). It returns a ranked portfolio of 15 ideas (top 5 + next 10) with how/perceive/implement notes, rubric scores, and red-team findings.
  2. Research + plan-pawl duel + Plan. Run research over the selected portfolio. Open-ended/high-risk work is fanout class: produce PerspectivePlan artifacts and a SynthesisPacket, then run the STEP 3.5 plan-pawl duel (two distinct families, ao plan-pawl decide) before /plan creates tracker rows — that duel verdict subsumes the premortem. Then run the normal artifact-first DAG over the approved packet rather than a single goal.
  3. Operationalize. Turn the ranked portfolio into a comprehensive, granular set of self-documenting beads — tasks, subtasks, dependency structure (ao beads exec dep add), and explicit test tasks (unit + e2e with detailed logging). Each bead carries what/why/how/risks/success so the original plan markdown never needs to be consulted again. Overlap-check against existing beads (ao beads exec list --json) before creating — merge, don't duplicate.
  4. Refine in plan space (4-5 passes). Before handing the packet to /crank, run 4-5 refinement passes over the bead set. Each pass: re-read AGENTS.md (especially after compaction), check every bead for sense and optimality, and DO NOT OVERSIMPLIFY / DO NOT LOSE FEATURES OR FUNCTIONALITY. Validate between passes (no dependency cycles; every leaf actionable via ao beads exec ready).

Tracking is br with bv triage — this is AgentOps. The operationalize and refine steps consume brainstorm's ideation output; see references/bead-operationalization.md.

Executable acceptance for this path: references/discovery.feature (ideation/operationalize/refine scenarios, ag-yw0).

Execution

Run the artifact-first DAG in references/dag.md. That file owns the executable workflow, state shape, gate detail, per-step detail, and the acceptance-criteria YAML contract.

Flags

Flag Default Description
--auto on Fully autonomous (no human gates). Inverse of --interactive. Passed through to /research and /plan.
--interactive off Human gates in research and plan (STEP 3, STEP 4). Does NOT affect premortem gate.
--skip-brainstorm auto Skip STEP 1 brainstorm when goal is already specific
--ideate auto Force the open-ended generate-winnow path: delegate to brainstorm --ideate (30→5→15), then operationalize into self-documenting br beads and refine 4-5x in plan space. Auto-on for open-ended goals. See Open-Ended Path.
--complexity=<level> auto Force complexity level (fast / standard / full)
--no-budget off Disable phase time budgets
--no-scaffold off Skip scaffold auto-invocation in STEP 4.5
--duel auto Run the plan-pawl cross-family duel at STEP 3.5. Auto-on for fanout class and --complexity=full; opt-in elsewhere. Subsumes the single-judge fanout approval + premortem council.
--no-duel off Skip the duel (MVP-slice class): single-Fable ApprovalEdge if approval is needed, plus the inline --quick premortem at STEP 5.
--duel-rounds=<N> 3 Max duel rounds before the max-attempts breaker trips (ao plan-pawl decide --max-rounds).

Quick Start

/discovery "add user authentication"              # full discovery
/discovery --interactive "refactor payment module" # human gates in research + plan
/discovery --skip-brainstorm "fix login bug"       # skip brainstorm for specific goals
/discovery --complexity=full "migrate to v2 API"   # force full council ceremony

Output Specification

  • Path: child artifacts under .agents/research/, .agents/plans/, and .agents/council/; dense packets and summaries under .agents/rpi/; load-bearing slices in the resolved tracker.
  • Filename: execution-packet.json for latest/per-run packets and phase-1-summary-YYYY-MM-DD-<goal-slug>.md for the compact summary; preserve child artifact names returned by their skills.
  • Format: compact markdown summary to stdout plus schema-valid JSON packet containing density fields, artifact links, acceptance examples, constraints, optional epic ID, tracker mode, and next action.
  • Exit code: run bash skills/discovery/scripts/validate.sh and require zero; for beads require ao beads exec show <epic_id> to resolve Gherkin slices, while tasklist mode requires .agents/rpi/tasklist.md with epic, slice, and Given/When/Then markers.
  • Downstream handoff: pass the dense packet and mode-appropriate tracker evidence to /crank and /validate; raw child output remains linked in its own artifact.

Quality Checklist

  • Every capability-gap claim cites the search that distinguishes missing work from existing machinery.
  • The packet preserves testable Given/When/Then behavior, non-goals, evidence, constraints, and one exact next action without embedding raw child transcripts.
  • Risk classification matches the gate used, and DONE is impossible until the planned slices exist in the active tracker.

Completion Markers

<promise>DONE</promise>      # Discovery complete AND persisted: beads mode requires a resolvable epic_id plus Gherkin-bearing child slices; tasklist mode requires .agents/rpi/tasklist.md with epic, slice, and Given/When/Then markers.
<promise>BLOCKED</promise>   # Report the actual class: fanout/hard gates may block directly; an ordinary MVP breaker blocks only after its bounded helper returns ESCALATE.

Troubleshooting

Read references/troubleshooting.md for common problems and solutions.

Reference Documents