Skip to content

Prat011/awesome-llm-skills / notion-spec-to-implementation

notion-spec-to-implementation

Unverified

Turns product or tech specs into concrete Notion tasks that Claude code can implement. Breaks down spec pages into detailed implementation plans with clear tasks, acceptance criteria, and progress tracking to guide development from requirements to completion.

reference/spec-parsing.md

View on GitHub
# Specification Parsing

## Finding the Specification

Before parsing, locate the spec page:

```
1. Search for spec:
   Notion:notion-search
   query: "[Feature Name] spec" or "[Feature Name] specification"
   
2. Handle results:
   - If found → use page URL/ID
   - If multiple → ask user which one
   - If not found → ask user for URL/ID

Example:
Notion:notion-search
query: "User Profile API spec"
query_type: "internal"
```

## Reading Specifications

After finding the spec, fetch it with `Notion:notion-fetch`:

1. Read the full content
2. Identify key sections
3. Extract structured information
4. Note ambiguities or gaps

```
Notion:notion-fetch
id: "spec-page-id-from-search"
```

## Common Spec Structures

### Requirements-Based Spec

```
# Feature Spec
## Overview
[Feature description]

## Requirements
### Functional
- REQ-1: [Requirement]
- REQ-2: [Requirement]

### Non-Functional
- PERF-1: [Performance requirement]
- SEC-1: [Security requirement]

## Acceptance Criteria
- AC-1: [Criterion]
- AC-2: [Criterion]
```

Extract:
- List of functional requirements
- List of non-functional requirements
- List of acceptance criteria

### User Story Based Spec

```
# Feature Spec
## User Stories
### As a [user type]
I want [goal]
So that [benefit]

**Acceptance Criteria**:
- [Criterion]
- [Criterion]
```

Extract:
- User personas
- Goals/capabilities needed
- Acceptance criteria per story

### Technical Design Doc

```
# Technical Design
## Problem Statement
[Problem description]

## Proposed Solution
[Solution approach]

## Architecture
[Architecture details]

## Implementation Plan
[Implementation approach]
```

Extract:
- Problem being solved
- Proposed solution approach
- Architectural decisions
- Implementation guidance

### Product Requirements Document (PRD)

```
# PRD: [Feature]
## Goals
[Business goals]

## User Needs
[User problems being solved]

## Features
[Feature list]

## Success Metrics
[How to measure success]
```

Extract:
- Business goals
- User needs
- Feature list
- Success metrics

## Extraction Strategies

### Requirement Identification

Look for:
- "Must", "Should", "Will" statements
- Numbered requirements (REQ-1, etc.)
- User stories (As a... I want...)
- Acceptance criteria sections
- Feature lists

### Categorization

Group requirements by:

**Functional**: What the system does
- User capabilities
- System behaviors
- Data operations

**Non-Functional**: How the system performs
- Performance targets
- Security requirements
- Scalability needs
- Availability requirements
- Compliance requirements

**Constraints**: Limitations
- Technical constraints
- Business constraints
- Timeline constraints

### Priority Extraction

Identify priority indicators:
- "Critical", "Must have", "P0"
- "Important", "Should have", "P1"
- "Nice to have", "Could have", "P2"
- "Future", "Won't have", "P3"

Map to implementation phases based on priority.

## Handling Ambiguity

### Unclear Requirements

When requirement is ambiguous:

```markdown
## Clarifications Needed

### [Requirement ID/Description]
**Current text**: "[Ambiguous requirement]"
**Question**: [What needs clarification]
**Impact**: [Why this matters for implementation]
**Assumed for now**: [Working assumption if any]
```

Create clarification task or add comment to spec.

### Missing Information

When critical info is missing:

```markdown
## Missing Information

- **[Topic]**: Spec doesn't specify [what's missing]
- **Impact**: Blocks [affected tasks]
- **Action**: Need to [how to resolve]
```

### Conflicting Requirements

When requirements conflict:

```markdown
## Conflicting Requirements

**Conflict**: REQ-1 says [X] but REQ-5 says [Y]
**Impact**: [Implementation impact]
**Resolution needed**: [Decision needed]
```

## Acceptance Criteria Parsing

### Explicit Criteria

Direct acceptance criteria:

```
## Acceptance Criteria
- User can log in with email and password
- System sends confirmation email
- Session expires after 24 hours
```

Convert to checklist:
- [ ] User can log in with email and password
- [ ] System sends confirmation email
- [ ] Session expires after 24 hours

### Implicit Criteria

Derive from requirements:

```
Requirement: "Users can upload files up to 100MB"

Implied acceptance criteria:
- [ ] Files up to 100MB upload successfully
- [ ] Files over 100MB are rejected with error message
- [ ] Progress indicator shows during upload
- [ ] Upload can be cancelled
```

### Testable Criteria

Ensure criteria are testable:

❌ **Not testable**: "System is fast"
✓ **Testable**: "Page loads in < 2 seconds"

❌ **Not testable**: "Users like the interface"
✓ **Testable**: "90% of test users complete task successfully"

## Technical Detail Extraction

### Architecture Information

Extract:
- System components
- Data models
- APIs/interfaces
- Integration points
- Technology choices

### Design Decisions

Note:
- Technology selections
- Architecture patterns
- Trade-offs made
- Rationale provided

### Implementation Guidance

Look for:
- Suggested approach
- Code examples
- Library recommendations
- Best practices mentioned

## Dependency Identification

### External Dependencies

From spec, identify:
- Third-party services required
- External APIs needed
- Infrastructure requirements
- Tool/library dependencies

### Internal Dependencies

Identify:
- Other features needed first
- Shared components required
- Team dependencies
- Data dependencies

### Timeline Dependencies

Note:
- Hard deadlines
- Milestone dependencies
- Sequencing requirements

## Scope Extraction

### In Scope

What's explicitly included:
- Features to build
- Use cases to support
- Users/personas to serve

### Out of Scope

What's explicitly excluded:
- Features deferred
- Use cases not supported
- Edge cases not handled

### Assumptions

What's assumed:
- Environment assumptions
- User assumptions
- System state assumptions

## Risk Identification

Extract risk information:

### Technical Risks
- Unproven technology
- Complex integration
- Performance concerns
- Scalability unknowns

### Business Risks
- Market timing
- Resource availability
- Dependency on others

### Mitigation Strategies

Note any mitigation approaches mentioned in spec.

## Spec Quality Assessment

Evaluate spec completeness:

✓ **Good spec**:
- Clear requirements
- Explicit acceptance criteria
- Priorities defined
- Risks identified
- Technical approach outlined

⚠️ **Incomplete spec**:
- Vague requirements
- Missing acceptance criteria
- Unclear priorities
- No risk analysis
- Technical details absent

Document gaps and create clarification tasks.

## Parsing Checklist

Before creating implementation plan:

☐ All functional requirements identified
☐ Non-functional requirements noted
☐ Acceptance criteria extracted
☐ Dependencies identified
☐ Risks noted
☐ Ambiguities documented
☐ Technical approach understood
☐ Scope is clear
☐ Priorities are defined

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall