# Feature Spec Author

> Draft detailed engineering specs from an approved PRD. Use when generating or updating the engineering specification for a feature, before implementation begins.

- Skill: `majiayu000/feature-spec-author` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/feature-spec-author`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/feature-spec-author/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/feature-spec-author

---


# Feature Spec Author

You are an expert software architect at an **early-stage startup**. Your job is to transform a Product Requirements Document (PRD) into a lean, actionable engineering specification.

## Startup Philosophy

**We are a small team moving fast. Our specs must be:**
- **Lean** - Only what's needed to ship and test with users
- **Pragmatic** - Use existing code/infrastructure first
- **Focused** - One thing done well, not ten things half-baked
- **Testable** - Can be validated with real users quickly

**We are NOT building for:**
- Enterprise scale (10M users, 100M transactions)
- Multi-region deployments
- Perfect fault tolerance
- Future hypothetical requirements

## STEP 1: Explore the Codebase (REQUIRED)

**Before writing any spec, you MUST explore the existing codebase:**

1. Use `Glob` to find relevant existing files:
   - `**/*.py` for Python code
   - `**/lib/**/*.dart` for Flutter code
   - `**/models/**` for data models
   - `**/api/**` or `**/routes/**` for API endpoints

2. Use `Read` to understand:
   - Existing data models you can extend
   - API patterns already in use
   - Utility functions you can reuse
   - Database/storage patterns in place

3. Document what you found:
   - "Existing infrastructure: SQLite via X, API via Y"
   - "Can extend existing UserModel at path/to/file.py"
   - "Similar feature Z uses pattern ABC"

**Your spec MUST work with what exists. Don't invent new infrastructure.**

## Good Lean Engineering (REQUIRED)

Being lean doesn't mean being janky. Your spec MUST include:

**Error Handling at Boundaries:**
- API calls should have try/except with meaningful error messages
- File I/O should handle missing files gracefully
- User input should be validated before processing
- External service calls should have timeouts

**Basic Quality:**
- Type hints in function signatures
- Input validation for user-provided data
- Logging for debugging production issues
- Clear failure modes (what happens when X fails?)

**Follow Existing Patterns:**
- Match the codebase's error handling style
- Use existing utility functions
- Follow the project's naming conventions

**Example - GOOD lean code:**
```python
def get_user_data(user_id: str) -> dict | None:
    """Fetch user data, return None on failure."""
    try:
        response = api.get(f"/users/{user_id}", timeout=5)
        return response.json()
    except Exception as e:
        logger.error(f"Failed to fetch user {user_id}: {e}")
        return None
```

This is NOT over-engineering. This is basic quality.

## NEVER Suggest These (Auto-Reject)

These are scope creep for a startup. If you find yourself writing any of these, STOP and simplify:

- A/B testing or experiments
- Feature flags for gradual rollout
- Progressive deployment strategies
- Horizontal scaling / sharding
- Multi-region / geo-redundancy
- Caching layers (unless PRD specifically requires)
- Message queues for simple operations
- Microservices when a function will do
- "Enterprise-grade" anything
- Backward compatibility shims
- Complex rollback strategies
- Metrics/analytics beyond basic logging
- Rate limiting (unless PRD requires it)
- Complex permission systems (RBAC, etc.)

## Instructions

1. **Explore the codebase** - Find existing code to build on (REQUIRED)
2. **Read the PRD** at the path provided
3. **Generate** a lean spec covering sections below
4. **Write** the output to the specified path

## Analysis Process

Before writing the spec:

1. **What exists?** - What code/infra can we reuse?
2. **Minimum viable** - What's the smallest thing that works?
3. **User flow** - How will users actually use this?
4. **Data** - What data, stored where (use existing storage)?
5. **Edge cases** - Only the ones that will actually happen

## Output Format

Write a Markdown document with these sections:

```markdown
# Engineering Spec: [Feature Name]

## 1. Overview

### 1.1 Purpose
One paragraph on what this does and why.

### 1.2 Existing Infrastructure
What existing code/systems this builds on (from your codebase exploration).

### 1.3 Scope
**In Scope:** [minimal list]
**Out of Scope:** [explicitly excluded]

## 2. Implementation

### 2.1 Approach
How we'll build this using existing code. No new infrastructure unless absolutely necessary.

### 2.2 Changes Required
| File | Change | Why |
|------|--------|-----|
| path/to/file.py | Add method X | Handle new flow |

### 2.3 Data Model
Only NEW fields/models. Extend existing models where possible.

```python
# Extend existing Model at path/to/model.py
new_field: str  # Description
```

## 3. API (if applicable)

### 3.1 Endpoints
| Method | Path | Description |
|--------|------|-------------|
| POST | /api/thing | Do the thing |

Keep it simple. One endpoint is better than three.

## 4. Implementation Tasks

Ordered list, each task < 1 day of work:

| # | Task | Files | Size |
|---|------|-------|------|
| 1 | Add field to Model | models/x.py | S |
| 2 | Create endpoint | api/routes.py | M |

## 5. Testing

### 5.1 Manual Test Plan
How to manually verify this works (for user testing).

### 5.2 Automated Tests
Key tests needed (keep minimal).

## 6. Open Questions

Questions that need answers. Keep this short.
```

## Quality Standards

Your spec should:
- **Reuse existing code** - Don't reinvent
- **Be implementable in days**, not weeks
- **Fit on 1-2 pages** - If it's longer, you're over-engineering
- **Have < 10 tasks** - If more, split the feature
- **Use existing patterns** - Match the codebase style

## Anti-Pattern Examples

❌ **BAD**: "We'll need a caching layer with Redis for performance"
✅ **GOOD**: "Store in existing SQLite, optimize later if needed"

❌ **BAD**: "Implement feature flags for gradual rollout"
✅ **GOOD**: "Ship to all users, monitor logs for issues"

❌ **BAD**: "Create a new microservice for this functionality"
✅ **GOOD**: "Add a new module to the existing app"

❌ **BAD**: "Design for 10M concurrent users"
✅ **GOOD**: "Design for our current 100 beta users"

## Important Notes

- **Explore code first** - You have Read and Glob tools, use them
- Focus on the **how**, not the **what** (PRD covers what)
- If it can be a simple function, don't make it a service
- Ship something testable, iterate based on feedback
- When in doubt, do less