Feature Parser

Feature Parser

Extract structured information from markdown feature proposals.

Purpose

Transform free-form or template-based markdown proposals into structured data that can be consumed by judges and analyzers.

Input

Markdown proposal text (either user-written or generated by proposal-builder).

Expected format (from template):

# Feature: [Title]

## Overview
[Description]

## Goals
- Goal 1
- Goal 2

## Requirements

### Must Have
- [ ] Requirement 1
- [ ] Requirement 2

### Nice to Have
- [ ] Optional 1

## Constraints
- Constraint 1
- Constraint 2

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Related Context
(Optional)

Processing Steps

Step 1: Extract Feature Title

Priority order:
1. H1 heading starting with "Feature:" → extract text after "Feature:"
2. First H1 heading → use as-is
3. First sentence of document → use first 50 chars
4. Fallback → "Unnamed Feature"

Examples:
"# Feature: User Notification System" → "User Notification System"
"# Real-time Notifications" → "Real-time Notifications"
"Add notifications to the app..." → "Add notifications to the app..."

Step 2: Extract Overview/Description

Find "## Overview" section:
- Extract all text until next ## heading
- Trim whitespace
- If not found: use first paragraph of document
- If empty: "No description provided"

Step 3: Extract Goals

Find "## Goals" section:
- Extract all bullet points (lines starting with -, *, +, or numbered)
- Clean formatting (remove bullet markers, trim whitespace)
- Return as array of strings

Example input:
## Goals
- Notify users of important events
- Support multiple channels
- Easy user configuration

Output: ["Notify users of important events", "Support multiple channels", "Easy user configuration"]

If section not found: []

Step 4: Extract Requirements

Find "## Requirements" section, then sub-sections:

**Must Have:**
- Find "### Must Have" subsection
- Extract checkbox items: - [ ] or - [x]
- Clean text (remove checkbox markers)
- Return as array

**Nice to Have:**
- Find "### Nice to Have" subsection
- Extract checkbox items
- Clean text
- Return as array

Example input:
### Must Have
- [ ] Database notification channel
- [x] Email notifications
- [ ] Mark as read

Output mustHave: ["Database notification channel", "Email notifications", "Mark as read"]

If subsections not found:
- Try to extract all items under "## Requirements" → put in mustHave
- If no requirements at all: mustHave = [], niceToHave = []

Step 5: Extract Constraints

Find "## Constraints" section:
- Extract all bullet points or paragraphs
- Return as array of strings

Example input:
## Constraints
- Must use Laravel Notification system
- Cannot modify User table structure
- Redis queue required

Output: ["Must use Laravel Notification system", "Cannot modify User table structure", "Redis queue required"]

If section not found: []

Step 6: Extract Success Criteria

Find "## Success Criteria" section:
- Extract all checkbox items or bullet points
- Clean text
- Return as array

Example input:
## Success Criteria
- [ ] 95% delivery rate
- [ ] <30 second latency
- User satisfaction > 8/10

Output: ["95% delivery rate", "<30 second latency", "User satisfaction > 8/10"]

If section not found: []

Step 7: Extract Related Context (Optional)

Find "## Related Context" or "## Context" section:
- Extract all text/links
- Return as single string

Example input:
## Related Context
- Related issue: #123
- Similar feature: app/Notifications/
- Docs: https://laravel.com/docs/notifications

Output: "Related issue: #123\nSimilar feature: app/Notifications/\nDocs: https://laravel.com/docs/notifications"

If section not found: null

Step 8: Extract Keywords for Codebase Search

Combine and extract keywords from:
- Feature title
- Goals
- Must-have requirements
- Constraints

Process:
1. Lowercase all text
2. Remove common words (the, and, or, to, for, of, a, an, in, on, etc)
3. Extract significant technical terms
4. Include framework/technology names
5. Deduplicate
6. Return top 10-15 keywords

Example:
Title: "User Notification System"
Goals: ["Notify users via email", "Real-time WebSocket delivery"]
Requirements: ["Laravel Notification class", "Database channel", "Queue integration"]

Keywords extraction:
- user, notification, system, email, real-time, websocket, delivery, laravel, database, channel, queue, integration

Return: ["notification", "user", "email", "websocket", "real-time", "laravel", "database", "queue", "channel", "integration"]

Output Format

interface ParsedProposal {
  // Basic info
  title: string;
  overview: string;

  // Planning details
  goals: string[];
  requirements: {
    mustHave: string[];
    niceToHave: string[];
  };
  constraints: string[];
  successCriteria: string[];

  // Additional context
  relatedContext: string | null;

  // For codebase search
  keywords: string[];

  // Metadata
  completeness: {
    hasGoals: boolean;
    hasRequirements: boolean;
    hasConstraints: boolean;
    hasSuccessCriteria: boolean;
    score: number;  // 0-100, based on filled sections
  };
}

Completeness Score Calculation:

score = 0
if title not "Unnamed Feature": score += 10
if overview not "No description provided": score += 10
if goals.length > 0: score += 20
if requirements.mustHave.length > 0: score += 30
if constraints.length > 0: score += 15
if successCriteria.length > 0: score += 15

Total: 100 points max

Example Complete Parse

Input Markdown:

# Feature: Real-time User Notifications

## Overview
Add notification system using Laravel's built-in Notification feature to alert
users about mentions, messages, and important updates.

## Goals
- Notify users of critical events instantly
- Support both email and in-app delivery
- Allow users to control notification preferences

## Requirements

### Must Have
- [ ] Notification class for UserMentioned event
- [ ] Database notification channel
- [ ] Email notification channel
- [ ] Integration with User model

### Nice to Have
- [ ] WebSocket for real-time delivery
- [ ] Push notifications

## Constraints
- Must use Laravel 12.x Notification system
- Follow existing queue configuration (Redis)
- Cannot modify User table structure

## Success Criteria
- [ ] 95% delivery rate
- [ ] Email sent within 30 seconds
- [ ] Zero disruption to existing features

## Related Context
- Existing: app/Notifications/WelcomeEmail.php
- Queue: config/queue.php (Redis driver)

Output:

{
  "title": "Real-time User Notifications",
  "overview": "Add notification system using Laravel's built-in Notification feature to alert users about mentions, messages, and important updates.",
  "goals": [
    "Notify users of critical events instantly",
    "Support both email and in-app delivery",
    "Allow users to control notification preferences"
  ],
  "requirements": {
    "mustHave": [
      "Notification class for UserMentioned event",
      "Database notification channel",
      "Email notification channel",
      "Integration with User model"
    ],
    "niceToHave": [
      "WebSocket for real-time delivery",
      "Push notifications"
    ]
  },
  "constraints": [
    "Must use Laravel 12.x Notification system",
    "Follow existing queue configuration (Redis)",
    "Cannot modify User table structure"
  ],
  "successCriteria": [
    "95% delivery rate",
    "Email sent within 30 seconds",
    "Zero disruption to existing features"
  ],
  "relatedContext": "Existing: app/Notifications/WelcomeEmail.php\nQueue: config/queue.php (Redis driver)",
  "keywords": [
    "notification",
    "user",
    "real-time",
    "email",
    "database",
    "laravel",
    "queue",
    "redis",
    "websocket",
    "mentioned",
    "delivery"
  ],
  "completeness": {
    "hasGoals": true,
    "hasRequirements": true,
    "hasConstraints": true,
    "hasSuccessCriteria": true,
    "score": 100
  }
}

Edge Cases

Minimal/Vague Proposal:

Add notifications

Output:

{
  "title": "Add notifications",
  "overview": "No description provided",
  "goals": [],
  "requirements": {
    "mustHave": [],
    "niceToHave": []
  },
  "constraints": [],
  "successCriteria": [],
  "relatedContext": null,
  "keywords": ["notifications", "add"],
  "completeness": {
    "hasGoals": false,
    "hasRequirements": false,
    "hasConstraints": false,
    "hasSuccessCriteria": false,
    "score": 20
  }
}

Non-standard Format:

I want to add a notification system to my Laravel app. It should send emails
when users are mentioned. Must work with the existing User model.

Output:

{
  "title": "I want to add a notification system to my Laravel app",
  "overview": "I want to add a notification system to my Laravel app. It should send emails when users are mentioned. Must work with the existing User model.",
  "goals": [],
  "requirements": {
    "mustHave": [],
    "niceToHave": []
  },
  "constraints": [],
  "successCriteria": [],
  "relatedContext": null,
  "keywords": ["notification", "system", "laravel", "app", "email", "user", "mentioned", "model"],
  "completeness": {
    "hasGoals": false,
    "hasRequirements": false,
    "hasConstraints": false,
    "hasSuccessCriteria": false,
    "score": 20
  }
}

Error Handling

Empty/null input:

{
  "title": "Unnamed Feature",
  "overview": "No description provided",
  "goals": [],
  "requirements": { "mustHave": [], "niceToHave": [] },
  "constraints": [],
  "successCriteria": [],
  "relatedContext": null,
  "keywords": [],
  "completeness": {
    "hasGoals": false,
    "hasRequirements": false,
    "hasConstraints": false,
    "hasSuccessCriteria": false,
    "score": 0
  }
}

Malformed markdown:

• Be lenient with parsing
• Extract whatever is recognizable
• Don't fail on missing headings
• Look for patterns (bullet lists, checkboxes) even without section headers

Multiple sections with same name:

• Use first occurrence
• Combine if it makes sense (e.g., multiple constraint sections → merge all)

Success Indicators

Good parse (score >= 70):

• Has title
• Has overview
• Has at least 2 goals
• Has at least 3 must-have requirements

Acceptable parse (score 40-69):

• Has title
• Has either goals OR requirements

Poor parse (score < 40):

• Missing critical information
• Recommend user use proposal template or proposal-builder

Usage

This skill is typically used in Phase 1 of super-dev orchestration:

Input proposal (from user or proposal-builder)
    ↓
feature-parser skill
    ↓
ParsedProposal object
    ↓
Used by: codebase-analyzer (keywords search)
         judge agents (understand what to evaluate)
         vote-aggregator (context for final report)