~aod-discover

# AOD Discover Skill

## Purpose

Unified discovery skill for the AOD Lifecycle's **Discover** stage. Handles idea capture, ICE scoring, evidence gathering, and PM validation with 3 entry points:

- **`/aod.discover`** — Full flow: capture idea + ICE score + evidence + PM validation + user story
- **`/aod.discover --seed`** — Seed mode: fast-track pre-vetted ideas (auto ICE, skip prompts, skip PM)
- **`/aod.idea`** — Capture only: capture idea + ICE score + evidence (no PM validation)
- **`/aod.validate`** — Validate only: submit existing idea for PM review + user story generation

## Entry Point Detection

Determine the entry point from the invoking command:
- If invoked via `/aod.discover --seed` → run **Seed Mode** (Steps 1, 2, 5a, 5b, 8-seed)
- If invoked via `/aod.discover` → run **Full Flow** (Steps 1-8)
- If invoked via `/aod.idea` → run **Capture Only** (Steps 1-5)
- If invoked via `/aod.validate` → run **Validate Only** (Steps 6-8)

### `--seed` Flag Detection

Check if arguments contain `--seed` flag. If present:
- Remove `--seed` from the idea description text
- Set entry point to **Seed Mode**
- Seed mode is designed for pre-vetted ideas (e.g., from consumer guides) that don't need scoring or validation

## Critical Constraints

**MUST** use `.aod/scripts/bash/create-issue.sh` for ALL GitHub Issue creation. NEVER call `gh issue create` directly.

**Why**: Direct `gh issue create` bypasses the board sync pipeline, causing issues to silently disappear from the project board. The `create-issue.sh` script delegates to `aod_gh_create_issue()` which includes automatic board placement via `aod_gh_add_to_board()`. See KB Entry #20 for root cause analysis.

**Prohibited pattern** (DO NOT use):
```bash
# WRONG — bypasses board sync
gh issue create --title "..." --label "stage:discover" --body "..."
```

**Required pattern**:
```bash
# CORRECT — includes board sync automatically
bash .aod/scripts/bash/create-issue.sh --title "Feature title" --body "Markdown body" --stage discover
```

## Source of Truth

**GitHub Issues are the sole source of truth for backlog items.** All idea state (ICE scores, status, evidence) is stored in the GitHub Issue body. BACKLOG.md is an auto-generated view regenerated from Issues.

---

## Step 1: Parse Input (Capture + Full Flow)

Extract the idea description from user arguments. If no description is provided, ask the user to describe their idea.

**File reference pattern**: If arguments contain `read #### F-NNN: {title} in {file_path}`, this is a directive to read the full feature section from the referenced consumer guide:

1. Open `{file_path}` using the Read tool
2. Locate the heading `#### F-NNN: {title}`
3. Extract everything from that heading down to (but not including) the next `---` separator
4. Use the extracted content as the idea description (title = heading, body = full epic block including Goal, Stories, Interface Contract, and DoD)

This pattern is generated by `/aod.kickstart` in the Quick Start Commands section of consumer guides. It enables one-command-per-feature GitHub Issue creation with the complete epic content.

**Preserve full input**: If the user provides detailed content beyond a summary (e.g., stories, acceptance criteria, interface contracts, Definition of Done), capture ALL of it verbatim. This full content is stored in the GitHub Issue body in Step 5a so downstream commands (`/aod.define`, `/aod.spec`) can build on it.

## Step 2: ID Assignment

The GitHub Issue number is the canonical idea ID. There is no separate `IDEA-NNN` numbering scheme.

- The ID is assigned automatically when `create-issue.sh` runs in Step 5a
- Refer to ideas by their GitHub Issue number using `#NNN` format (e.g., `#42`)
- No scanning, parsing, or incrementing is needed — GitHub handles ID assignment

## Step 3: Capture Source and ICE Score

### Source

Use AskUserQuestion to determine the idea source:

```
Question: "Where did this idea come from?"
Options:
  - Brainstorm: "Generated during a brainstorming or planning session"
  - Customer Feedback: "Reported by a customer or based on user research"
  - Team Idea: "Suggested by a team member during development"
  - User Request: "Directly requested by a user or stakeholder"
```

### ICE Scoring

Present each ICE dimension using AskUserQuestion:

#### Impact — "How much value does this deliver to users?"

```
Options:
  - High (9): "Transformative — significant user value"
  - Medium (6): "Solid improvement — meaningful but incremental"
  - Low (3): "Minor enhancement — small quality-of-life fix"
```

Allow "Other" for custom numeric values (1-10).

#### Confidence — "How sure are we this will succeed?"

```
Options:
  - High (9): "Proven pattern — strong evidence it will work"
  - Medium (6): "Some unknowns — reasonable confidence with gaps"
  - Low (3): "Speculative — significant uncertainty"
```

Allow "Other" for custom numeric values (1-10).

#### Effort (Ease of Implementation) — "How easy is this to build?"

```
Options:
  - High (9): "Days of work — straightforward implementation"
  - Medium (6): "Weeks of work — moderate complexity"
  - Low (3): "Months of work — significant engineering effort"
```

Allow "Other" for custom numeric values (1-10).

**Compute**: ICE Total = Impact + Confidence + Effort (range 3-30)

## Step 4: Evidence Prompt (Capture + Full Flow)

After ICE scoring, prompt the user for evidence supporting this idea.

Use AskUserQuestion:

```
Question: "Who has this problem, and how do you know?"
Header: "Evidence"
Options:
  - Customer Feedback: "Based on direct customer reports, support tickets, or user research"
  - Team Observation: "Noticed by the team during development, testing, or internal usage"
  - Analytics Data: "Supported by usage metrics, error rates, or behavioral analytics"
  - User Request: "Explicitly requested by a user, stakeholder, or partner"
```

Allow "Other" for free-text evidence statements.

**Store the response** as the `evidence` field. This value is used in:
- Step 5a: GitHub Issue body (`## Evidence` section)
- Step 6: PM validation (evidence quality evaluation)
- BACKLOG.md Discover section (Evidence column)

**If the user selects a predefined category**: Store as `"{Category}: {any additional detail}"` if they provide detail, or just `"{Category}"` if not.

**If the user provides free text via "Other"**: Store the full text as-is.

## Step 5: Apply Auto-Defer Gate

Determine status based on ICE total:

- **Total < 12**: Set status to **"Deferred"** (auto-deferred)
- **Total >= 12**: Set status to **"Scoring"**

**If auto-deferred AND entry point is Full Flow (`/aod.discover`)**:
- Create GitHub Issue (Step 5a) and regenerate BACKLOG.md (Step 5b), then **STOP**. Do not proceed to PM validation.
- Display result with guidance:

```
IDEA CAPTURED — AUTO-DEFERRED

ID: #{NNN}
Idea: {description}
Source: {source}
Evidence: {evidence}
ICE Score: {total} (I:{impact} C:{confidence} E:{effort})
Priority Tier: Deferred
Status: Deferred

This idea was auto-deferred (score < 12).
To request PM override: `/aod.validate #{NNN}`
To re-score with new information: `/aod.score #{NNN}`
```

**If auto-deferred AND entry point is Capture Only (`/aod.idea`)**: Create GitHub Issue, display same result, exit.

**If NOT auto-deferred AND entry point is Capture Only (`/aod.idea`)**: Create GitHub Issue, display result and exit:

```
IDEA CAPTURED

ID: #{NNN}
Idea: {description}
Source: {source}
Evidence: {evidence}
Date: {YYYY-MM-DD}
ICE Score: {total} (I:{impact} C:{confidence} E:{effort})
Priority Tier: {tier}
Status: Scoring

Next: Run `/aod.validate #{NNN}` to submit for PM review, or continue capturing ideas with `/aod.idea`.
```

**If NOT auto-deferred AND entry point is Full Flow (`/aod.discover`)**: Continue to Step 5a, then Step 5c.

## Step 5a: GitHub Issue Creation (All Entry Points)

Create a GitHub Issue for lifecycle tracking:

1. Build the issue body using the structured format. If the user provided detailed content (stories, acceptance criteria, interface contracts, DoD), include it in the `## Detail` section:
   ```markdown
   ## Idea

   {idea_summary — first sentence or goal line}

   ## Detail

   {full user-provided content: stories, acceptance criteria, interface contracts, DoD, etc.
   Include verbatim — do not summarize or omit. Omit this section if user only provided a summary.}

   ## ICE Score
   Impact: {impact}, Confidence: {confidence}, Effort: {effort} = **{total}**

   ## Evidence
   {evidence}

   ## Metadata
   - Source: {source}
   - Priority: {priority_tier}
   - Date: {YYYY-MM-DD}
   - Status: {status}
   ```

2. **MUST** use the standalone `create-issue.sh` script (do NOT call `gh issue create` directly — the script handles both issue creation and project board sync):
   ```bash
   bash .aod/scripts/bash/create-issue.sh \
     --title "{idea_description}" \
     --body "$BODY" \
     --stage discover \
     --type idea
   ```
   The script outputs the issue number on stdout. Capture it — this becomes the canonical idea ID (`#NNN`).

3. If `gh` is unavailable, skip silently (graceful degradation).

## Step 5b: Regenerate BACKLOG.md

After GitHub Issue creation, run `.aod/scripts/bash/backlog-regenerate.sh` to update the backlog snapshot. If `gh` is unavailable, skip silently.

## Step 5c: Check Governance Tier (Full Flow only)

Before proceeding to PM validation in the Full Flow (`/aod.discover`), check the governance tier:

1. Read `.aod/memory/constitution.md`
2. Find the governance tier configuration (`governance:` → `tier:` value)
3. Valid values: `light`, `standard`, `full`. Default: `standard`

**If tier is `light`**:
- PM validation is **optional** — skip Steps 6-7 in the Full Flow
- Display note: "Note: Light governance tier — PM validation skipped. Run `/aod.validate #NNN` to manually request PM review."
- Exit. The user can still manually invoke `/aod.validate #NNN` at any time

**If tier is `standard` or `full`**: Continue to Step 6 as normal.

**Note**: The `/aod.validate` entry point always runs PM validation regardless of tier — it is an explicit user request for PM review.

## Step 6: PM Validation (Validate + Full Flow)

### For `/aod.validate` entry point: Parse and find idea

Extract the idea identifier from user arguments. Accept three formats:
- **`NNN`** (bare number, e.g., `21`): Direct GitHub Issue lookup
- **`#NNN`** (hash-prefixed, e.g., `#21`): Strip `#` prefix, direct lookup
- **`IDEA-NNN`** (legacy, e.g., `IDEA-009`): Search issue titles for `[IDEA-NNN]` bracket tag

If invalid or missing, display: `Usage: /aod.validate NNN` (or `#NNN` or `IDEA-NNN`)

Find the matching GitHub Issue:

For numeric input (`NNN` or `#NNN`):
```bash
source .aod/scripts/bash/github-lifecycle.sh && aod_gh_find_issue NNN
```

For legacy `IDEA-NNN` input:
```bash
source .aod/scripts/bash/github-lifecycle.sh && aod_gh_find_issue "[IDEA-NNN]"
```

**Error conditions**:
- Issue not found: `"Error: No GitHub Issue found for {identifier}"`
- Issue already has `stage:define` or later: `"Error: #{issue_number} has already progressed past discovery"`

Read the issue body to extract idea details (description, ICE score, evidence, source, status).

Display idea for review:

```
IDEA FOR PM VALIDATION

ID: #{issue_number}
Idea: {description}
Source: {source}
Evidence: {evidence}
Date: {date}
Status: {status}
ICE Score: {total} (I:{impact} C:{confidence} E:{effort})
Priority Tier: {tier}
Auto-Deferred: {Yes if status is Deferred, otherwise No}
```

### Launch PM Review

Use the Task tool with `product-manager` subagent_type:

```
Review this idea for product backlog inclusion:

Idea: {idea_description}
ICE Score: {total} (I:{impact} C:{confidence} E:{effort})
Priority Tier: {tier}
Current Status: {status}
Auto-Deferred: {yes/no}
Evidence: {evidence}

Evaluate:
1. Does this idea align with the product vision and roadmap?
2. Is the ICE scoring reasonable given the idea description?
3. Does this idea deliver meaningful user value?
4. Should this idea enter the product backlog as a user story?
5. Is the evidence sufficient to justify pursuing this idea? Evaluate the quality and
   specificity of the evidence provided.

If evidence is empty or "No evidence provided", flag this:
"No evidence provided — recommend gathering evidence before proceeding."
You may still approve if the idea has strong merit despite missing evidence, but note
the evidence gap in your rationale.

If auto-deferred (score < 12), provide additional justification for why this idea
should or should not override the auto-defer gate.

Respond with:
STATUS: [APPROVED | REJECTED]
EVIDENCE_QUALITY: [Strong | Adequate | Weak | Missing]
RATIONALE: [Your detailed reasoning — 2-4 sentences]
```

### Handle Rejection

If PM returns **REJECTED**:
1. Update the GitHub Issue: add a comment with PM rejection rationale and update the `Status:` line in the body to "Rejected"
2. Display rejection and exit:

```
PM VALIDATION: REJECTED

ID: #{issue_number}
Idea: {description}
PM Rationale: {rationale}

The idea has been marked as Rejected on GitHub Issue #{issue_number}.
To re-submit: re-score with `/aod.score #{issue_number}`, then run `/aod.validate #{issue_number}` again.
```

### Handle Approval

If PM returns **APPROVED**: Continue to Step 7.

## Step 7: User Story Generation

1. **Generate user story**: Transform idea into "As a [persona], I want [action], so that [benefit]" format.
   - Default persona: "Template Adopter" if not evident from idea.
2. **Present for confirmation**: Use AskUserQuestion:
   ```
   Options:
     - Accept: "Save this user story as-is"
     - Edit: "Let me modify the user story text"
   ```
3. **Determine priority**: Map ICE score to priority rank:
   - P0 (25-30): Priority = 1
   - P1 (18-24): Priority = 2
   - P2 (12-17): Priority = 3
   - Deferred (<12, PM override): Priority = 4

## Step 8: Update GitHub Issue and Report

### Update GitHub Issue

1. Update the GitHub Issue body to include the user story in a new `## User Story` section
2. Update `Status:` in the body to "Validated"
3. Add a comment documenting PM approval with rationale and evidence quality
4. If idea was auto-deferred and PM approved, add PM override note as a comment:
   ```
   **PM Override**: #{issue_number} was auto-deferred (ICE score {total} < 12) but approved by PM. Rationale: {pm_rationale}
   ```

### Regenerate BACKLOG.md

Run `.aod/scripts/bash/backlog-regenerate.sh` to update the backlog snapshot.

### Report result

**For `/aod.validate` entry point**:
```
PM VALIDATION: APPROVED

ID: #{issue_number}
Idea: {description}
Evidence Quality: {evidence_quality}
PM Rationale: {rationale}

User Story Created:
  Story: "{user_story_text}"
  Priority: {priority}
  Status: Validated

GitHub Issue #{issue_number} updated with user story and PM approval.

Next: Run `/aod.define {topic}` to create a PRD from this user story.
```

**For `/aod.discover` entry point (full flow)**:
```
AOD DISCOVERY COMPLETE

Idea Captured:
  ID: #{issue_number}
  Description: {description}
  Source: {source}
  Evidence: {evidence}

ICE Scoring:
  Score: {total} (I:{impact} C:{confidence} E:{effort})
  Priority Tier: {tier}

PM Validation: APPROVED
  Evidence Quality: {evidence_quality}
  Rationale: {rationale}

User Story Created:
  Story: "{user_story_text}"
  Priority: {priority}
  Status: Validated

Next: Run `/aod.define {topic}` to create a PRD from this user story.
```

---

## ICE Scoring Reference

### Quick-Assessment Anchors

| Dimension | High (9) | Medium (6) | Low (3) |
|-----------|----------|------------|---------|
| **Impact** | Transformative | Solid improvement | Minor enhancement |
| **Confidence** | Proven pattern | Some unknowns | Speculative |
| **Effort (Ease)** | Days of work | Weeks of work | Months of work |

### Priority Tiers

| Score Range | Priority | Action |
|-------------|----------|--------|
| 25-30 | P0 (Critical) | Fast-track to development |
| 18-24 | P1 (High) | Queue for next sprint |
| 12-17 | P2 (Medium) | Consider when capacity allows |
| < 12 | Deferred | Auto-defer; requires PM override via `/aod.validate` |

### Auto-Defer Gate

Ideas scoring below 12 are automatically deferred. In the full flow (`/aod.discover`), the flow stops and no PM validation occurs. Use `/aod.validate #NNN` to request PM override for deferred ideas.

---

## Seed Mode (`--seed` Flag)

Seed mode is a fast-track path for pre-vetted ideas (e.g., from a consumer guide generated by `/aod.kickstart`). It skips all interactive prompts, auto-assigns sensible defaults, and creates the GitHub Issue immediately.

### When to Use

- Importing seed stories from a consumer guide
- Batch-loading pre-planned features into the backlog
- Any idea where scoring and validation are unnecessary because the idea is already committed

### Seed Mode Flow

1. **Step 1 (Parse Input)**: Extract idea description (strip `--seed` from arguments). If empty, ask for description.
2. **Step 2 (ID Assignment)**: Same as normal — GitHub Issue number is canonical ID.
3. **Auto-assign defaults** (skip Steps 3-4):
   - **Source**: `Consumer Guide`
   - **ICE Score**: Impact=8, Confidence=7, Effort=7 (Total=22, P1 High)
   - **Evidence**: `Seed story from consumer guide — pre-vetted during kickstart planning`
4. **Skip auto-defer gate** (Step 5): Score is 22, always passes.
5. **Step 5a (GitHub Issue Creation)**: Create issue with `stage:discover` label using `create-issue.sh`, same structured body format.
6. **Step 5b (Regenerate BACKLOG.md)**: Same as normal.
7. **Skip PM validation** (Steps 5c-7): No governance check, no PM review, no user story generation.
8. **Report result**:

```
SEED IDEA CAPTURED

ID: #{issue_number}
Idea: {description}
Source: Consumer Guide
ICE Score: 22 (I:8 C:7 E:7)
Priority Tier: P1 (High)
Status: Scoring

Seed mode — ICE scoring, evidence, and PM validation skipped.
Next: Run `/aod.define {topic}` to create a PRD, or continue seeding with `/aod.discover --seed`.
```

### Seed Mode Defaults

| Field | Default Value | Rationale |
|-------|---------------|-----------|
| Source | `Consumer Guide` | Pre-vetted during kickstart |
| Impact | 8 | High — guide features are user-facing |
| Confidence | 7 | Good — planned but not yet validated |
| Effort | 7 | Moderate — typical feature scope |
| Evidence | `Seed story from consumer guide — pre-vetted during kickstart planning` | Acknowledges provenance |
| Status | `Scoring` | Ready for define stage |

---

## Edge Cases

- **No description provided**: Prompt user for idea description
- **Custom ICE score outside 1-10**: Clamp to valid range (1 minimum, 10 maximum)
- **Duplicate idea text**: Allow it — GitHub assigns a unique issue number automatically
- **Issue not found** (validate): Search GitHub Issues by number, display error if not found
- **Already Rejected** (validate): Cannot re-validate directly — user must re-score first with `/aod.score`
- **Already past discovery** (validate): Cannot re-validate — idea has progressed
- **PM timeout or error**: Report the error and suggest retrying
- **User edits story to empty string**: Re-prompt for user story text
- **PM approves auto-deferred idea**: Document override rationale as GitHub Issue comment
- **Auto-deferred in full flow**: Flow stops — no PM validation, no user story
- **`gh` unavailable**: Skip GitHub Issue creation silently (graceful degradation)
- **`--seed` with no description**: Prompt for idea description (flag alone is not enough)

## Quality Checklist

- [ ] GitHub Issue created via `create-issue.sh` (NOT `gh issue create` directly) with structured body, `stage:discover` label, and `type:idea` label
- [ ] Entry point correctly detected (discover/discover --seed/idea/validate)
- [ ] `--seed` flag: stripped from description, defaults applied, prompts skipped
- [ ] Idea ID is the GitHub Issue number (`#NNN`), assigned by `create-issue.sh`
- [ ] Source captured from user selection
- [ ] Evidence prompted after ICE scoring (predefined categories + free text)
- [ ] Evidence included in GitHub Issue body and display outputs
- [ ] ICE score computed correctly (additive I+C+E)
- [ ] Auto-defer gate applied (< 12 = Deferred, flow stops in full flow)
- [ ] Issue added to Projects board with correct Status column (verified via script output)
- [ ] BACKLOG.md regenerated after Issue creation
- [ ] Governance tier read from constitution (light/standard/full, default: standard)
- [ ] Light tier: PM validation skipped in full flow, with note to user
- [ ] PM validation includes evidence quality evaluation (Strong/Adequate/Weak/Missing)
- [ ] PM validation invoked via Task tool (product-manager subagent)
- [ ] Rejection: GitHub Issue updated, flow exits
- [ ] Approval: User story generated in proper format
- [ ] User story presented for confirmation
- [ ] GitHub Issue updated with user story and PM approval
- [ ] PM override documented if idea was auto-deferred
- [ ] BACKLOG.md regenerated after validation
- [ ] Result reported with next step guidance

---

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I'll just use `gh issue create` directly — same result" | Critical Constraints (line 34) require `create-issue.sh`; direct `gh` bypasses board sync per the line 38 warning. |
| "Score 11 is close enough — I'll skip the auto-defer gate" | Step 5 (line 162) hard-codes < 12 as Deferred and stops the full flow before PM review. |
| "Evidence is optional, I'll mark it 'No evidence provided'" | Step 6 PM prompt (line 336) flags empty evidence; PM may approve but documents the gap in rationale. |
| "Seed mode skips ICE — I can use it for any quick idea" | Seed Mode (line 481) is for pre-vetted consumer-guide stories only; defaults Impact=8, Confidence=7 per line 493. |
| "Light tier means PM validation is permanently disabled" | Step 5c (line 261) skips PM in full flow only; line 267 confirms `/aod.validate` always runs PM regardless. |

## Red Flags

- Agent calls `gh issue create` directly, bypassing `aod_gh_add_to_board` per line 36 KB Entry #20.
- Agent advances an auto-deferred idea to PM validation without `/aod.validate` override per Step 5 (line 167).
- Agent skips Step 5b BACKLOG.md regeneration after Issue creation, leaving the snapshot stale per line 248.
- Agent assigns a separate `IDEA-NNN` ID instead of using the GitHub Issue number per Step 2 (line 73).
- Agent ignores legacy `IDEA-NNN` format support in Step 6 (line 276) and rejects valid input.
- Agent submits the user story without the AskUserQuestion confirmation step per Step 7 (line 375).