discovery

Original：🇺🇸 English
Translated

Full discovery phase orchestrator. Brainstorm + ao search + research + plan + pre-mortem gate. Produces epic-id and execution-packet for /crank. Triggers: "discovery", "discover", "explore and plan", "research and plan", "discovery phase".

20installs
Sourceboshu2/agentops
Added on

NPX Install

npx skill4agent add boshu2/agentops discovery

Tags

Translated version includes tags in frontmatter
discovery-phase-orchestrationworkflow-automationepic-managementpre-mortem-analysiscli-tool

SKILL.md Content

View Translation Comparison →

/discovery — Full Discovery Phase Orchestrator

Quick Ref: Brainstorm → search history → research → plan → pre-mortem. Produces an epic-id and execution-packet ready for 
/crank
.
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Quick Start

bash
/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

Architecture

/discovery <goal> [--interactive] [--complexity=<fast|standard|full>] [--skip-brainstorm]
  │
  ├── Step 1: Brainstorm (optional)
  │   └── /brainstorm <goal> — clarify WHAT before HOW
  │
  ├── Step 2: Search History
  │   └── ao search "<goal keywords>" — surface prior learnings
  │
  ├── Step 3: Research
  │   └── /research <goal> — deep codebase exploration
  │
  ├── Step 4: Plan
  │   └── /plan <goal> — decompose into epic + issues
  │
  └── Step 5: Pre-mortem (gate)
      └── /pre-mortem — council validates the plan
          PASS/WARN → output epic-id + execution-packet
          FAIL → re-plan with findings, max 3 attempts

Execution Steps

Step 0: Setup

bash
mkdir -p .agents/rpi
Initialize state:
discovery_state = {
  goal: "<goal string>",
  interactive: <true if --interactive>,
  complexity: <fast|standard|full or null for auto-detect>,
  skip_brainstorm: <true if --skip-brainstorm or goal is >50 chars and specific>,
  epic_id: null,
  attempt: 1,
  verdict: null
}
CLI dependency detection:
bash
# Tracking mode
if command -v bd &>/dev/null; then TRACKING_MODE="beads"; else TRACKING_MODE="tasklist"; fi

# Knowledge flywheel
if command -v ao &>/dev/null; then AO_AVAILABLE=true; else AO_AVAILABLE=false; fi

Step 1: Brainstorm (optional)

Skip if: 
--skip-brainstorm
flag, OR goal is >50 chars and contains no vague keywords (improve, better, something, somehow, maybe), OR a brainstorm artifact already exists for this goal in 
.agents/brainstorm/
.
Otherwise: Invoke 
/brainstorm
to clarify WHAT before HOW:
Skill(skill="brainstorm", args="<goal>")
If brainstorm produces a refined goal, use the refined goal for subsequent steps.

Step 2: Search History

Skip if: 
ao
CLI is not available.
Otherwise: Search for prior session learnings relevant to the goal:
bash
ao search "<goal keywords>" 2>/dev/null || true
ao lookup --query "<goal keywords>" --limit 5 2>/dev/null || true
Summarize any relevant findings (prior attempts, related decisions, known constraints) and carry them forward as context for research.
Ranked packet requirement: Before leaving discovery, assemble a lightweight ranked packet for the current goal:
  • matching compiled planning rules / pre-mortem checks
  • matching active findings from 
    .agents/findings/*.md
  • matching unconsumed high-severity items from 
    .agents/rpi/next-work.jsonl
Rank by literal goal-text overlap first, then issue-type / work-shape overlap, then file-path or module overlap when known. Discovery does not need the final file list yet, but it MUST surface the best matching high-severity next-work items so planning can incorporate them instead of rediscovering them later.

Step 3: Research

Invoke 
/research
for deep codebase exploration:
Skill(skill="research", args="<goal> [--auto]")
Pass 
--auto
unless 
--interactive
was specified. Research output lands in 
.agents/research/
.

Step 3.1: Identify Applicable Test Levels

After research completes, determine which test levels (L0–L3) the goal requires. Read the test pyramid standard (
test-pyramid.md
in the standards skill) for the full pyramid and selection guide.
Ask:
  • Does the change touch external APIs or I/O? → L0 + L1 + L2 minimum
  • Does it cross module boundaries? → Add L2
  • Does it affect a full subsystem workflow? → Add L3
Record the applicable levels in 
discovery_state.test_levels
for downstream 
/plan
consumption.

Step 4: Plan

Invoke 
/plan
to decompose into an epic with trackable issues:
Skill(skill="plan", args="<goal> [--auto]")
Pass 
--auto
unless 
--interactive
was specified. Plan output lands in 
.agents/plans/
and creates issues via 
bd
or TaskList.
After plan completes:
  1. Extract epic ID: 
    bd list --type epic --status open
    (beads) or identify from TaskList.
  2. Store in 
    discovery_state.epic_id
    .
  3. Carry forward the ranked packet summary (applied findings, known risks, high-severity next-work matches) into the execution packet and phase summary.
  4. Auto-detect complexity (if not overridden):
    • Count issues: 
      bd children <epic-id> | wc -l
    • Low: 1-2 issues → 
      fast
    • Medium: 3-6 issues → 
      standard
    • High: 7+ issues or 3+ waves → 
      full

Step 5: Pre-mortem (gate)

Invoke 
/pre-mortem
to validate the plan:
Skill(skill="pre-mortem", args="[--quick]")
Use 
--quick
for fast/standard complexity. Use full council (no 
--quick
) for full complexity or 
--deep
override.
Gate logic (max 3 attempts):
  • PASS/WARN: Proceed. Store verdict in 
    discovery_state.verdict
    .
  • FAIL: Retry loop:
    1. Read pre-mortem report: 
      ls -t .agents/council/*pre-mortem*.md | head -1
    2. Extract structured findings (description, fix, ref)
    3. Log: 
      "Pre-mortem: FAIL (attempt N/3) -- retrying plan with feedback"
    4. Re-invoke 
      /plan
      with findings context: 
      Skill(skill="plan", args="<goal> --auto --context 'Pre-mortem FAIL: <findings>'")
    5. Re-invoke 
      /pre-mortem
    6. If still FAIL after 3 total attempts, stop: 
      "Pre-mortem failed 3 times. Last report: <path>. Manual intervention needed."
      Output: 
      <promise>BLOCKED</promise>

Step 6: Output

After successful gate (PASS/WARN): write execution packet and phase summary (read 
references/output-templates.md
for formats), record ratchet, output 
<promise>DONE</promise>
, and report epic-id with suggested next step: 
/crank <epic-id>
. Include 
test_levels
from Step 3.1 in the execution packet for 
/crank
consumption.

Flags

FlagDefaultDescription
--interactive
offHuman gates in research and plan
--skip-brainstorm
autoSkip brainstorm step
--complexity=<level>
autoForce complexity level (fast/standard/full)
--no-budget
offDisable phase time budgets

Completion Markers

<promise>DONE</promise>      # Discovery complete, epic-id + execution-packet ready
<promise>BLOCKED</promise>   # Pre-mortem failed 3x, manual intervention needed

Examples

bash
/discovery "add user authentication"              # full discovery
/discovery --interactive "refactor payment module" # human gates
/discovery --skip-brainstorm "fix login bug"       # skip brainstorm

Troubleshooting

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

Reference Documents

  • references/complexity-auto-detect.md — precedence contract for keyword vs issue-count classification
  • references/idempotency-and-resume.md — re-run safety and resume behavior
  • references/phase-budgets.md — time budgets per complexity level
  • references/troubleshooting.md — common problems and solutions
  • references/output-templates.md — execution packet and phase summary formats
See also: brainstorm, research, plan, pre-mortem, crank, rpi