Feature Research

YOU ARE READING THIS SKILL RIGHT NOW

STOP. Before doing ANYTHING else:

1. ☐ Verify session mode supports this workflow
2. ☐ Create TodoWrite checklist (see below)
3. ☐ Mark Step 1 as in_progress
4. ☐ Read AGENTS.md first, then CLAUDE.md/docs before any code

This skill produces 2 files: directive specification (Z01_research.md) + structured questions (Z01_CLARIFY.md)

MANDATORY FIRST ACTION: Create TodoWrite

TodoWrite({
  todos: [
    {content: "Step 0: Verify session mode and proceed in Default mode", status: "in_progress", activeForm: "Checking collaboration mode"},
    {content: "Step 1: Read documentation FIRST (AGENTS.md, CLAUDE.md, README, ARCHITECTURE)", status: "pending", activeForm: "Reading project docs"},
    {content: "Step 2: Explore code (glob, grep, read files)", status: "pending", activeForm: "Analyzing codebase"},
    {content: "Step 3: Create Z01 research file (directive specification)", status: "pending", activeForm: "Writing research"},
    {content: "Step 4: Create Z01_CLARIFY file (structured questions)", status: "pending", activeForm: "Extracting ambiguities"},
    {content: "Step 5: Verify directive nature (no questions in research)", status: "pending", activeForm: "Validating specification"},
    {content: "Step 6: Resolve/track Z01_CLARIFY and block handoff until cleared", status: "pending", activeForm: "Waiting for clarification resolution"}
  ]
})

After each step: Mark completed, move in_progress to next step.

The Iron Law

NO RESEARCH WITHOUT READING AGENTS.MD FIRST
NO Z01_CLARIFY WITH 5 OR MORE QUESTIONS WITHOUT INVOKING BRAINSTORMING
NO PLANNING WITHOUT FILE PATHS + LINE RANGES
NO Z01 THAT REQUIRES READING ANOTHER DOCUMENT TO UNDERSTAND THE WORK

If you skip AGENTS.md or CLAUDE.md: You'll violate project patterns. Delete Z01, start over.

If Z01_CLARIFY has 5 or more questions: Design is unclear. Stop research, invoke superpowers:brainstorming to clarify requirements first.

If Z01_research lacks file paths: Planner can't proceed. Add exact files + line ranges or don't create Z01.

If Z01_research references another doc for core requirements ("see spec/PRD/ticket"): Z01 is invalid. Copy required source context into Z01 and rewrite to be self-contained.

Research Output Format

Single directive: One clear approach (preserves existing patterns from AGENTS.md, CLAUDE.md, and docs)

Primary + 1 alternative: Only if alternative is significantly better for specific use case

• Primary approach MUST preserve existing patterns from AGENTS.md, CLAUDE.md, and docs
• Alternative approach has different trade-offs (e.g., microservice vs monolith)
• Both options have complete technical details (files, line ranges, pros/cons)
• User chooses, then update Z01_research.md to be fully directive

Workflow Steps

Step 0: Session Mode Check

This workflow runs in Default mode or Plan mode. Proceed in the current mode; do not block on Plan mode availability.

Step 1: Read Documentation FIRST

MANDATORY FIRST - read these if they exist:

• AGENTS.md (default repo instructions, patterns, conventions)
• CLAUDE.md (Claude-specific patterns, conventions, forbidden approaches)
• README.md (architecture overview)
• ARCHITECTURE.md (system design)
• All documentation (glob "/docs//*.md")

Why: AGENTS.md sets the default repo rules, and CLAUDE.md may add mandatory patterns or forbidden approaches. Primary solution MUST preserve these patterns.

Step 2: Explore Code

Find related files, search for patterns, read key files.

Document:

• Files to change with line ranges
• APIs and integration points
• Data shapes and types
• Security considerations
• Edge cases and failure modes
• Test requirements
• Environment variables
• Source proposal/spec details that drive implementation scope

Step 3: Create Research File

Scan for ongoing directory:

• Check for existing Z01 files
• Common locations: docs/ai/ongoing, .ai/ongoing, docs/ongoing
• Create default docs/ai/ongoing if none found

Save ONGOING_DIR location for Step 4.

File: {ONGOING_DIR}/Z01_{feature}_research.md

Sanitize feature name:

• Use snake_case: lowercase with underscores
• Replace spaces and special chars with underscores
• Remove quotes, slashes, colons
• Truncate to 50 characters
• Example: "OAuth 2.0 Authentication!" → "oauth_2_0_authentication"

Structure (key sections only):

# {Feature} Research

## Summary
One paragraph: what and why.

## Source Context (Self-Contained)
- Original user proposal/spec intent copied into this file
- Functional and non-functional requirements from source docs
- Constraints, assumptions, and explicit out-of-scope items from source docs
- Include enough detail so planning/implementation can proceed without opening the source doc

## Current State
What exists. Files: path/to/file.py:123-145

## Existing Patterns & Documentation
### From AGENTS.md and CLAUDE.md
- Conventions that MUST be followed
- Architectural patterns to preserve
- Forbidden patterns/approaches

### Repository Structure
- Directory/file naming patterns

## Proposed Implementation

### Primary Approach (Preserves Existing Patterns)
- Architecture: How it fits existing system
- Files: path/to/file.py:50-75 - What changes
- Data shapes, APIs, integration points
- Security, edge cases, test requirements

### Alternative Approach (Optional - only if significantly better)
- Why different: [specific advantages]
- Architecture, files, data shapes
- Trade-offs vs primary

## Integration Points
How this connects to existing code.

## Environment Variables
- VAR_NAME - purpose

Self-contained requirement (MANDATORY):

• Z01 must stand on its own for planning and implementation.
• Do not require readers to open spec/idea/PRD/ticket documents for core requirements.
• If external docs are mentioned, summarize or copy the relevant requirements into Z01.
• Phrases like "see spec", "refer to ticket", "details in doc X" are only allowed for optional background, never for required implementation details.

Step 4: Create CLARIFY File

File: {ONGOING_DIR}/Z01_CLARIFY_{feature}_research.md

Every ambiguity, technology choice, or missing requirement:

Agent question: {concise question}
User response:

Agent question: {next question}
User response:

Critical: Leave "User response:" blank. No explanations.

When incorporating answered questions: Delete fully-answered CLARIFY files or remove incorporated Q&A pairs if only some were answered.

Phase Gate: After creating Z01_CLARIFY, count the questions.

If 5 or more questions:

1. STOP - don't proceed to Step 5
2. Design is too unclear for research
3. Delete both Z01_research.md and Z01_CLARIFY.md
4. Announce: "Design unclear (5+ questions). Using superpowers:brainstorming to clarify requirements first."
5. Use Skill tool to invoke superpowers:brainstorming
6. After brainstorming completes, start feature-research again from Step 1

If fewer than 5 questions: Proceed to Step 5

Step 5: Verify Directive Nature

Check Z01_research.md for vague questions:

• "Should we...?" → Move to CLARIFY
• "Options include..." (vague) → Make directive OR move to CLARIFY
• "We could..." (incomplete) → Make directive OR move to CLARIFY

Acceptable: Primary + 1 alternative with complete details for both Not acceptable: Vague alternatives, 3+ options, questions embedded

Step 6: Completion Gate (CLARIFY Controls Done State)

Research is NOT complete while Z01_CLARIFY_{feature}_research.md exists with unresolved items.

Unresolved means ANY of the following:

• File still contains Agent question: entries
• Any User response: is blank
• Answers were provided but not yet incorporated into Z01_{feature}_research.md

If unresolved CLARIFY exists:

1. Keep research todo as in_progress (do NOT mark workflow complete)
2. Report only: "Waiting for Z01_CLARIFY_{feature}_research.md answers/incorporation before planning."
3. Do NOT invoke or suggest feature-planning yet

Only mark research complete when:

1. Clarification answers are incorporated into Z01_{feature}_research.md
2. Z01_CLARIFY_{feature}_research.md is deleted (or has no remaining Q&A pairs)
3. Research file is directive and has no open questions

Red Flags - You're Failing If:

• Did NOT read AGENTS.md/CLAUDE.md/README/docs FIRST
• Stopped this skill due to missing Plan mode
• Primary approach violates AGENTS.md or CLAUDE.md patterns
• Z01_CLARIFY has 5 or more questions but didn't invoke brainstorming
• Marked research done while Z01_CLARIFY still has unresolved items
• More than 2 files created
• No file paths or line ranges
• Questions embedded in Z01_research.md
• CLARIFY has explanations (should be questions only)
• Missing "Existing Patterns" section
• Using hardcoded paths (detect pattern instead)
• Vague file references (need path + line ranges)
• Z01 depends on external docs for core requirements

Common Rationalizations

Success Criteria

You followed the workflow if:

• ✓ Read AGENTS.md/CLAUDE.md/README/docs FIRST
• ✓ Verified session mode supports workflow before Step 1
• ✓ "Existing Patterns" section in Z01_research.md
• ✓ Primary approach preserves patterns from AGENTS.md and CLAUDE.md
• ✓ If Z01_CLARIFY has 5 or more questions: invoked superpowers:brainstorming and restarted
• ✓ Exactly 2 files: Z01_research.md + Z01_CLARIFY.md (fewer than 5 questions)
• ✓ Z01_research.md is directive (single OR primary + 1 alternative)
• ✓ If alternative: both have complete technical details
• ✓ File paths + line ranges included
• ✓ Z01_research.md includes copied/summarized source proposal context and is self-contained
• ✓ CLARIFY uses exact format (questions only, blank responses)
• ✓ Research stays in_progress until CLARIFY is fully resolved and removed
• ✓ Implementer can code without architectural decisions

When to Use

Use when:

• Design direction is clear from brainstorming
• Need thorough technical research before planning
• Need to understand integration points, APIs, data shapes, security

Don't use when:

• Design is still unclear → Use superpowers:brainstorming first
• Simple changes (typo fixes, trivial updates)
• Already have complete technical specification

Handoff to Planning

If CLARIFY has unresolved items:

1. Announce: "Research not complete yet. Waiting for Z01_CLARIFY answers/incorporation."
2. Keep research workflow open (do not handoff)

When CLARIFY is fully resolved and removed:

1. Announce: "Research complete. Z01_research.md ready for planning."
2. Then proceed to planning workflow

What planning receives:

• Patterns that MUST be preserved (from AGENTS.md and CLAUDE.md)
• Forbidden approaches to AVOID
• Files that MUST be modified (with line ranges)
• APIs/libraries required
• Security/integration requirements
• When to proceed (user approval trigger)