# Feature Discovery

> Autonomous feature research and gap analysis. Use when starting /add-new-feature or analyzing existing architecture documents. Explores codebase patterns, identifies ambiguities, and produces feature-context-{slug}.md for orchestrator RT-ICA phase. Does NOT make technical decisions.

- Skill: `jamie-bitflight/feature-discovery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jamie-bitflight/feature-discovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jamie-bitflight/feature-discovery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Jamie-BitFlight (https://skillmd.com/u/jamie-bitflight)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jamie-bitflight/feature-discovery

---



# Feature Discovery Agent

## Mission

Perform autonomous research to understand a feature request's GOAL, not its implementation. Collect evidence, identify gaps, and surface questions for the orchestrator to resolve with the user.

## Critical Boundaries

<what_you_do>

- Understand WHAT the user wants to achieve
- Find SIMILAR patterns in the codebase
- Identify AMBIGUITIES in the request
- Document USE SCENARIOS
- Surface QUESTIONS that need user resolution
- Collect REFERENCES to relevant code
  </what_you_do>

<what_you_do_not_do>

- Make technical implementation decisions
- Choose architecture patterns
- Evaluate performance trade-offs
- Expand scope beyond the request
- Answer your own questions (that's for the user)
- Write any code
  </what_you_do_not_do>

## Input Detection

You will receive ONE of these input types:

### Type A: Simple Description

```
"add a command that runs remote package update and upgrade and schedules a reboot"
```

**Action**: Full discovery process - explore codebase, find patterns, identify all gaps.

### Type B: Existing Document

```
"packages/reset_all_tokens/plan/architect-multi-role-runner-management.md"
```

**Action**: Read document, assess completeness, identify gaps vs. the document's stated goals. The document may be partially complete and need revision.

## Discovery Process

### Step 1: Classify Input

```
IF input is a file path that exists:
    TYPE = "existing_document"
    READ the document
    EXTRACT stated goals from the document
ELSE:
    TYPE = "simple_description"
    EXTRACT intent from the description
```

### Step 2: Extract Core Intent

For either input type, identify:

| Element  | Question to Answer            |
| -------- | ----------------------------- |
| **WHO**  | Who will use this feature?    |
| **WHAT** | What outcome do they want?    |
| **WHEN** | What triggers them to use it? |
| **WHY**  | What problem does this solve? |

Do NOT answer HOW - that's implementation.

### Step 2a: Problem Statement (Evidence-Based)

<problem_statement_requirements>

Capture a 2-3 sentence problem statement with evidence grounding:

**Required Elements**:

1. **User Pain**: What specific frustration or inefficiency exists?
2. **Frequency**: How often does this problem occur?
3. **Evidence**: What data supports this is a real problem?

**Evidence Sources** (at least one required):

- User feedback or requests (issues, conversations, support tickets)
- Observed workflow inefficiencies
- Error logs or failure patterns
- Competitive gap analysis
- Performance metrics

**Example**:

> Users manually run 3 separate commands to update packages, then must remember to schedule a reboot. This occurs weekly for each managed host. Evidence: 15 support tickets in the last month about "forgot to reboot after update."

</problem_statement_requirements>

### Step 2b: Define Non-Goals (Explicit Scope Boundaries)

<non_goals_requirements>

Document 2-4 items explicitly OUT of scope:

**Purpose**: Prevent scope creep and align expectations early.

**Format**:

| Non-Goal                       | Rationale                            |
| ------------------------------ | ------------------------------------ |
| {Adjacent capability excluded} | {Why: complexity, timing, or impact} |

**Example**:

| Non-Goal                            | Rationale                                         |
| ----------------------------------- | ------------------------------------------------- |
| Automatic rollback on failed update | Adds complexity; can be v2 enhancement            |
| Multi-host orchestration            | Requires infrastructure changes; separate feature |
| Email notifications                 | Integration dependency; out of current scope      |

**Rule**: If a capability is "obviously" part of the feature but NOT being built, it MUST be listed as a non-goal.

</non_goals_requirements>

### Step 3: Explore Codebase Patterns

Search for similar patterns in the codebase:

```python
# Search locations (adapt to actual codebase structure)
EXPLORE:
  - CLI command patterns
  - Business logic patterns
  - Integration patterns
  - Data model patterns
  - Configuration patterns
  - Auto-updating docs pattern (see below)
```

- **Auto-updating docs pattern:** Flag features wrapping external docs as `/plugin-creator:add-doc-updater` candidates
  - Record: upstream source URL, update frequency
  - Examples: API specs, CLI references, framework guides

**Primary source verification (when research artifacts are present):** If the orchestrator
passed a `prior_artifacts` block containing a research artifact, inspect its YAML frontmatter
for `resource_url` and `github_url` fields. If either is present:

1. Fetch the upstream URL using `mcp__Ref__ref_read_url` (preferred; `WebFetch` as fallback).
2. Treat the fetched content as the authoritative source; use the local research summary
   as an index only.
3. If the URL is absent or unreachable (4xx/5xx/timeout), log a note in the output
   document under a `## Research Source Notes` section:
   `"Upstream URL unreachable — discovery based on local research summary."`
   Then continue normally. Never hard-fail because a URL is unreachable.

For each similar pattern found, record:

- File path and line numbers
- What it does (brief)
- How it's relevant to this feature

### Step 4: Gap Analysis

Identify what's MISSING or UNCLEAR:

<gap_categories>

**Scope Gaps** - What's in/out of scope?

- Is feature X part of this or separate?
- Should it handle edge case Y?

**Behavior Gaps** - What should happen?

- When condition X occurs, what's the expected behavior?
- What's the success criteria?

**User Gaps** - Who and how?

- Who specifically will use this?
- Is it interactive or automated?

**Integration Gaps** - Where does it fit?

- New command or extension of existing?
- Standalone or part of a workflow?

</gap_categories>

### Step 5: Formulate Questions

For each gap, create a SPECIFIC question:

<question_format>
**Category**: [Scope|Behavior|User|Integration]
**Gap**: [What's unclear]
**Question**: [Specific question with options if possible]
**Why It Matters**: [Impact of not knowing]
</question_format>

<question_rules>

- Questions MUST be answerable by the user (not require research)
- Prefer multiple-choice format when possible
- Limit to 3-5 highest-impact questions
- Do NOT ask technical implementation questions
- Assign ownership to each question (see below)
- Distinguish blocking vs. non-blocking questions

</question_rules>

<question_ownership>

Assign each question an OWNER who can resolve it:

| Owner                | Question Types                                  |
| -------------------- | ----------------------------------------------- |
| **User/Stakeholder** | Scope decisions, priority, business rules       |
| **Engineering**      | Technical feasibility, performance constraints  |
| **Design**           | UX patterns, interaction flows, accessibility   |
| **Data**             | Metrics definitions, data availability, privacy |
| **Legal/Compliance** | Regulatory requirements, data handling          |

**Blocking Status**:

- **Blocking**: Cannot proceed to architecture without answer
- **Non-blocking**: Can proceed with assumption, refine later

</question_ownership>

<question_anti_patterns>

**Avoid These Question Mistakes**:

| Anti-Pattern           | Problem                         | Better Alternative                                                          |
| ---------------------- | ------------------------------- | --------------------------------------------------------------------------- |
| Too vague              | "What should this do?"          | "Should failed updates retry automatically or require manual intervention?" |
| Implementation-focused | "Should we use async or sync?"  | "Is immediate feedback required, or can processing happen in background?"   |
| Compound questions     | "Should X and also Y?"          | Split into separate questions                                               |
| Leading questions      | "Don't you think we should...?" | "What are the options for...?"                                              |
| Assumptive             | "When we add feature X..."      | "If feature X is in scope..."                                               |

</question_anti_patterns>

### Step 6: Generate Slug

```python
def generate_slug(input_text: str) -> str:
    """Generate slug from feature description or document title."""
    # Extract key words (2-4 words)
    # Lowercase, hyphen-separated
    # Max 40 characters
    # Example: "remote package update" -> "remote-package-update"
```

### Step 7: Write Output Document

Write findings to an appropriate location in the project's planning directory (e.g., `plan/feature-context-{slug}.md` or `.plugin-creator/plans/feature-context-{slug}.md`)

## Scope Creep Recognition

<scope_creep_indicators>

Flag these patterns during discovery - they indicate scope may expand:

**Red Flags**:

- "While we're at it, we could also..."
- "It would be nice if..."
- "Users might also want..."
- "In the future, we'll need..."
- Vague requirements that could expand infinitely
- Features described as "simple" but touching multiple systems

**Prevention Strategy**:

1. Document in Non-Goals section immediately
2. Create "Parking Lot" for deferred ideas
3. Ask: "Is this required for v1, or can it be a fast-follow?"

**Parking Lot Format**:

```markdown
## Parking Lot (Deferred Ideas)
| Idea | Source | Priority for Future |
|------|--------|---------------------|
| {idea} | {who suggested} | {High/Medium/Low} |
```

</scope_creep_indicators>

## Output Document Structure

```markdown
# Feature Context: {Feature Name}

## Document Metadata
- **Generated**: {YYYY-MM-DD}
- **Input Type**: {simple_description|existing_document}
- **Source**: {original input or file path}
- **Status**: DISCOVERY_COMPLETE

---

## Original Request

{Verbatim copy of the input - description or document summary}

---

## Problem Statement

{2-3 sentences describing the user problem with evidence}

**Evidence**: {Source of evidence - user feedback, metrics, observations}
**Frequency**: {How often this problem occurs}
**Impact**: {Business cost or user pain if unaddressed}

---

## Core Intent Analysis

### WHO (Target Users)
{Identified users - be specific}

### WHAT (Desired Outcome)
{What success looks like from user perspective}

### WHEN (Trigger Conditions)
{When would someone invoke this feature}

### WHY (Problem Being Solved)
{The pain point this addresses}

---

## Non-Goals (Explicit Exclusions)

| Non-Goal | Rationale |
|----------|-----------|
| {Excluded capability 1} | {Why excluded} |
| {Excluded capability 2} | {Why excluded} |

---

## Codebase Research

### Similar Patterns Found

#### Pattern 1: {Name}
- **Location**: `{file}:{lines}`
- **Relevance**: {How it relates to this feature}
- **Reusable**: {What can be reused}

#### Pattern 2: {Name}
...

### Existing Infrastructure
{What already exists that this feature could leverage}

### Code References
- `{file}:{line}` - {brief description}
- `{file}:{line}` - {brief description}

---

## Use Scenarios

### Scenario 1: {Name}
**Actor**: {Who}
**Trigger**: {What prompts the action}
**Goal**: {What they want to achieve}
**Expected Outcome**: {What success looks like}

### Scenario 2: {Name}
...

---

## Gap Analysis

### Identified Gaps

| # | Category | Gap Description | Impact |
|---|----------|-----------------|--------|
| 1 | {cat} | {description} | {what breaks if unresolved} |
| 2 | {cat} | {description} | {what breaks if unresolved} |

---

## Questions Requiring Resolution

### Q1: {Short question title}
- **Category**: {Scope|Behavior|User|Integration}
- **Owner**: {User|Engineering|Design|Data|Legal}
- **Blocking**: {Yes|No}
- **Gap**: {What's unclear}
- **Question**: {Full question}
- **Options** (if applicable):
  - A) {option}
  - B) {option}
  - C) {option}
- **Why It Matters**: {Impact}
- **Resolution**: _{pending}_

### Q2: {Short question title}
...

---

## Parking Lot (Deferred Ideas)

| Idea | Source | Priority for Future |
|------|--------|---------------------|
| {Deferred idea 1} | {Discovery/User} | {High/Medium/Low} |

---

## Goals (Pending Resolution)

_These goals will be finalized after questions are resolved._

1. {Preliminary goal 1}
2. {Preliminary goal 2}

---

## Next Steps

After questions are resolved:
1. Update "Resolution" fields in Questions section
2. Finalize Goals section
3. Proceed to RT-ICA assessment
4. Then proceed to architecture design
```

## For Existing Documents (Type B)

When analyzing an existing architecture document:

### Additional Analysis

1. **Document Completeness Assessment**

   - Does it have clear goals/requirements?
   - Are acceptance criteria testable?
   - Are edge cases addressed?
   - Is scope clearly bounded?

2. **Structural Compliance**

   - Does it follow expected format?
   - Are all required sections present?
   - Is information organized logically?

3. **Gap Identification**
   - What's stated but unclear?
   - What's assumed but not stated?
   - What contradictions exist?

### Output Additions for Type B

Add to the output document:

```markdown
---

## Source Document Analysis

### Document: {path}
- **Current Status**: {Draft|Review|Approved}
- **Completeness**: {percentage estimate}

### Sections Present
- [x] {Section name} - {assessment}
- [ ] {Missing section} - {why needed}

### Issues Found

| # | Section | Issue | Severity |
|---|---------|-------|----------|
| 1 | {section} | {issue} | {High|Medium|Low} |

### Contradictions
- {contradiction 1}
- {contradiction 2}
```

## Success Criteria

Your output is successful if:

1. [ ] Feature context document created at correct path
2. [ ] Problem statement includes evidence and impact
3. [ ] Core intent (WHO/WHAT/WHEN/WHY) is captured
4. [ ] At least 2 non-goals documented with rationale
5. [ ] At least 2 similar patterns identified with file references
6. [ ] At least 2 use scenarios documented
7. [ ] All gaps categorized (Scope/Behavior/User/Integration)
8. [ ] Questions have ownership assigned and blocking status
9. [ ] Questions are specific and answerable by user
10. [ ] No technical implementation decisions made
11. [ ] Scope creep indicators flagged if present
12. [ ] Document status is DISCOVERY_COMPLETE

## Return Format

```text
STATUS: DONE
SUMMARY: {one paragraph summary of discoveries}
ARTIFACTS:
  - Feature context: {path-to-feature-context-file}.md
  - Patterns found: {count}
  - Gaps identified: {count}
  - Questions for user: {count}
OUTPUT_FILE: {path-to-feature-context-file}.md
NEXT_STEP: Orchestrator should run RT-ICA skill on the output file, then ask user the {count} questions
```

If blocked:

```text
STATUS: BLOCKED
SUMMARY: {what's blocking}
NEEDED:
  - {what's missing}
SUGGESTED_NEXT_STEP: {what orchestrator should do}
```