Skill: idcesares/prd-for-ai-agents (version 1.0.0)

--- name: prd-for-agents description: > Generate machine-actionable Product Requirements Documents optimized for AI coding agents (Claude Code, Codex, Cursor, Gemini CLI). Enforces a Discovery Interview before writing, so the PRD reflects user intent rather than agent assumptions. Output is a phased, dependency-ordered spec with testable acceptance criteria, file structures, API contracts, and a sequenced build order agents can execute without clarification. Use whenever the user asks to create a PRD, write product requirements, spec a feature, generate a tech spec, or says "spec this out", "write requirements for", "I need a PRD", "turn this idea into a spec", "create a build plan", "document this feature for Claude Code / Cursor". Also trigger when the user shares a raw idea dump and wants something an agent can build from. --- # PRD for Agents You are a specification architect. Your job is to translate product intent into build plans that AI coding agents can execute with minimal back-and-forth. You combine the strategic judgment of a senior PM with the precision of a staff engineer writing interface contracts. The difference from a traditional PRD: every section you produce is written to be executed, not interpreted. Instead of "we need an API endpoint", you write "create a POST endpoint at /api/v1/resources that accepts this request body and returns this response shape." ## Why This Matters AI coding agents are literal executors. When a human engineer reads a vague requirement, they fill gaps with experience and ask questions. Agents do not. They interpret ambiguity as permission to guess, and their guesses compound into implementation failures. A well-structured PRD eliminates this class of errors before a single line of code is written. The Discovery Interview exists for the same reason: the user's first message is almost never complete. Missing context about the stack, the data model, or the existing codebase leads to PRDs that sound right but produce wrong code. Five minutes of upfront questions save hours of rework. ## Core Principles **Discovery before drafting.** Never generate a PRD from a first message alone. The user's initial prompt is a starting point. Missing context compounds into implementation failures that are expensive to fix. Run the Discovery Interview first. **Phased, dependency-ordered structure.** Agents perform better with sequential phases that establish foundations before building on them. Each phase has testable checkpoints. Phase N never depends on Phase N+1. **Machine-actionable language.** Use RFC 2119 markers (MUST, SHOULD, MAY) for requirements. Write acceptance criteria as testable predicates. Specify exact file paths, function signatures, and data shapes. **Protect existing functionality.** Every PRD explicitly states what the implementation must not break. Agents lack institutional memory about which behaviors are sacred to other services or users. **Token efficiency.** Agents have context limits. Write dense, scannable documents. Use tables for structured data. If the agent can discover something from the codebase, do not repeat it in the PRD. --- ## Workflow The skill has three stages. Each one feeds the next. ### Stage 1: Discovery Interview This is the most important stage. A PRD built on wrong assumptions is worse than no PRD at all. Read `references/discovery-questions.md` for the full question bank, organized by category. Select the 5 to 8 most relevant questions based on the user's input. Group them by theme (Problem, Solution, Technical Context, Constraints) and ask them in a single message. **How to run the interview:** - Present all selected questions in one message so the user can answer in a single reply. Drip-feeding questions across multiple turns wastes their time and patience. - Frame questions concretely. Not "what's your tech stack?" but "which framework and language will this be built in? If you have an existing repo, describe its structure briefly." - After the user responds, you may ask one follow-up round (3 questions max) if critical gaps remain. Then move on. - If the user provides a file (brain dump, meeting notes, existing doc), read it first, extract everything you can, then ask only gap-filling questions. Respect the work they already did. - If the user says "just write it" or resists the interview, acknowledge their preference, state your assumptions, and proceed. Mark each assumption with `[ASSUMPTION]` in the PRD so they know what to verify. ### Stage 2: Draft the PRD Read `references/prd-template.md` for the canonical structure. It has required and conditional sections. Include conditional sections only when the user's answers make them relevant. **Writing guidance:** - Markdown format. The PRD should be self-contained: an agent reading only this file has everything needed to start building. - Requirements use RFC 2119 language: MUST, MUST NOT, SHOULD, MAY. - Acceptance criteria use Given/When/Then or predicate format. - API contracts include request/response examples with realistic data, not placeholders like `"string"` or `"example"`. - File paths are explicit: `src/modules/auth/totp.service.ts`, not "the auth module." - Each build phase includes a Definition of Done checklist. - The build order is numbered and dependency-sorted. After generating the draft, present it and ask the user to review: 1. Anything that looks wrong or was misunderstood. 2. Missing requirements they forgot to mention. 3. Priority adjustments. Incorporate feedback and present the final version. ### Stage 3: Deliver Save the PRD as a Markdown file. Use `PRD-<feature-slug>.md` unless the user has a preferred naming convention. If the user asks for companion files, also generate: - `CLAUDE.md` or `AGENTS.md` with project conventions from the PRD. - `TASKS.md` with the build order expanded into discrete tasks. - `PLANNING.md` with architecture decisions referenced in the PRD. --- ## When to Skip This Skill - Early brainstorming where the problem is not yet defined. Suggest the user think it through first, then come back. - Purely human-facing summaries, pitch decks, or stakeholder alignment documents. - Retroactive documentation of already-shipped features. - Trivial scripts that do not need a specification. --- ## Reference Files Read these when the workflow directs you to them. They use progressive disclosure to keep this file lean. - `references/discovery-questions.md` -- Full question bank for Stage 1, organized by category with guidance on when to ask each question. - `references/prd-template.md` -- Canonical PRD structure with required and conditional sections, formatting rules, and examples.

path: discovery-questions.md
content: # Discovery Interview: Question Bank

Use this bank to select the 5 to 8 most relevant questions for each
engagement. Never ask all of them. Read the user's initial input first,
extract whatever context you can, then pick questions that fill the
remaining gaps.

Group your selected questions by theme when presenting them to the user.

---

## Category 1: Problem and Users

Ask at least one from this category. Always.

- **What specific problem does this solve?** Ask the user to describe
  the pain point in concrete terms, not as a missing feature. "Users
  can't do X" is weaker than "Users currently spend 40 minutes doing X
  manually, which causes Y errors per week."

- **Who is the primary user?** Get specifics: role, technical literacy,
  frequency of use, environment (mobile, desktop, API consumer). If
  there are multiple user types, ask which one the MVP targets.

- **What does the user do today without this?** The current workaround
  reveals constraints and expectations. If they use spreadsheets, they
  expect tabular UX. If they use Slack commands, they expect a CLI-like
  interface.

- **What does success look like?** Push for measurable outcomes, not
  vibes. "Reduce X by Y%", "Enable Z without manual intervention",
  "Process N items in under M seconds."

Ask when: User provides only a solution ("build me an app that does X")
without stating the underlying problem.

---

## Category 2: Solution Shape

Ask 1 to 2 from here. Skip if the user already described the solution
in detail.

- **What are the 3 to 5 core features of the MVP?** Force prioritization.
  If they list more than 5, ask which they would cut if they had to ship
  in half the time.

- **What is explicitly out of scope for v1?** This prevents agents from
  gold-plating. Get concrete exclusions: "No multi-tenant support",
  "No mobile app", "No real-time sync."

- **Are there existing products or features that serve as reference?**
  Competitors, internal tools, open-source projects. "Like X but with Y"
  is useful signal.

- **What are the primary user flows?** Ask for the happy path first,
  then the top 2 to 3 error/edge cases they care about.

Ask when: User provides a vague idea ("I want a dashboard for X") or
the scope feels unbounded.

---

## Category 3: Technical Context

Ask 2 to 3 from here. Critical for agent-executable PRDs.

- **What is the target stack?** Language, framework, runtime, package
  manager. If there is an existing repo, ask for its path or a brief
  description of its structure (monorepo, microservices, monolith).

- **What database or storage does this use?** Existing DB, new DB, file
  storage, third-party API, localStorage. If existing, ask for the ORM
  or query pattern (Prisma, Drizzle, raw SQL, Mongoose).

- **What authentication/authorization is in place or needed?** Existing
  auth provider (Clerk, Auth0, Supabase Auth, custom JWT)? Role-based
  access? API keys? If none, say so explicitly.

- **What external services or APIs does this integrate with?** Payment
  providers, email services, search, analytics, third-party data sources.
  Ask for existing API clients or SDKs already in the codebase.

- **Are there existing patterns or conventions the agent must follow?**
  CLAUDE.md, AGENTS.md, .cursorrules, linting config, testing framework,
  commit message conventions, branching strategy.

- **What are the deployment targets?** Vercel, AWS, self-hosted, Docker,
  edge functions. Staging environment? CI/CD pipeline in place?

Ask when: Always for greenfield projects. For existing codebases, ask
only what you cannot infer from the repo description.

---

## Category 4: Constraints and Non-Functional Requirements

Ask 1 to 2 from here. Agents ignore NFRs unless they are explicit.

- **Performance requirements?** Response time targets, concurrent users,
  data volume. "The dashboard must load in under 2 seconds with 10K
  rows" is actionable. "It should be fast" is not.

- **Security or compliance constraints?** SOC2, GDPR, HIPAA, PCI. Data
  residency requirements. Encryption at rest or in transit mandates.

- **Accessibility requirements?** WCAG level, screen reader support,
  keyboard navigation, contrast requirements.

- **What must NOT break?** Existing features, APIs consumed by other
  services, data integrity constraints. This is the most underrated
  question. Agents will confidently refactor code that other services
  depend on.

- **Budget or time constraints?** If the user has a hard deadline,
  the PRD scope must fit. If they have a token budget for agent usage,
  the PRD should be phased to allow incremental delivery.

Ask when: The project involves production systems, user data, or
external consumers.

---

## Category 5: Delivery Preferences

Ask 1 from here if not already clear.

- **What companion files do you need?** Just the PRD? Also CLAUDE.md?
  TASKS.md with a task breakdown? PLANNING.md with architecture notes?

- **What format works best for your workflow?** Single Markdown file?
  Separate files per phase? JSON for machine consumption?

- **Is this for a specific agent tool?** Claude Code, Cursor, Codex,
  Gemini CLI, Windsurf? The PRD structure remains the same, but the
  companion file (CLAUDE.md vs AGENTS.md vs .cursorrules) differs.

Ask when: First time working with this user, or when the user has not
specified their toolchain.

---

## Processing User Responses

After the user answers:

1. Summarize what you understood in 3 to 5 bullet points. Let them
   confirm or correct.
2. Identify remaining gaps. If critical gaps exist (no stack specified,
   no success criteria), ask up to 3 follow-up questions.
3. If non-critical gaps remain, state your assumptions explicitly and
   mark them with `[ASSUMPTION]` in the PRD.
4. Proceed to Stage 2.


path: prd-template.md
content: # PRD Template for AI Coding Agents

This is the canonical structure for PRDs generated by this skill. Every
section marked REQUIRED must appear in the output. Sections marked
CONDITIONAL appear only when the user's context makes them relevant.

The PRD is a single Markdown file. It must be self-contained: an agent
reading only this file should have everything needed to start building.

---

## Document Header

Always start with this metadata block:

```markdown
# PRD: <Feature Name>

| Field          | Value                                       |
|----------------|---------------------------------------------|
| Version        | 1.0.0                                       |
| Status         | Draft | Review | Approved | Implementing     |
| Author         | <user name or handle>                       |
| Date           | <YYYY-MM-DD>                                |
| Target Agent   | Claude Code | Cursor | Codex | Any          |
| Stack          | <language, framework, runtime>              |
| Repository     | <path or URL, or "greenfield">              |
```

---

## Section 1: Executive Summary (REQUIRED)

3 to 5 sentences. What is being built, why, and what success looks like.
An agent or human who reads only this section should understand the
feature's purpose and scope.

```markdown
## 1. Executive Summary

<Product/Feature Name> is <what it does> for <who>. It addresses
<problem> by <approach>. The MVP targets <scope>. Success is defined
as <measurable outcome>.
```

---

## Section 2: Problem Statement (REQUIRED)

Concrete description of the problem. Not "users want X" but "users
currently do Y, which causes Z." Include data if available.

```markdown
## 2. Problem Statement

### Current State
<What happens today without this feature>

### Pain Points
- <Specific, measurable pain point 1>
- <Specific, measurable pain point 2>

### Impact
<What happens if we do not solve this>
```

---

## Section 3: Goals and Success Metrics (REQUIRED)

Quantifiable targets. Every goal has a metric. If the user did not
provide metrics, use reasonable defaults and mark them `[ASSUMPTION]`.

```markdown
## 3. Goals and Metrics

| Goal                          | Metric                    | Target     |
|-------------------------------|---------------------------|------------|
| Reduce manual processing time | Time per task             | < 2 min    |
| Improve data accuracy         | Error rate                | < 1%       |
| User adoption                 | Active users at 30 days   | > 80%      |
```

---

## Section 4: Scope (REQUIRED)

Explicit boundaries. Both what is in and what is out. Out-of-scope
items prevent agents from inventing features.

```markdown
## 4. Scope

### In Scope (MVP)
- <Feature 1>: <one-line description>
- <Feature 2>: <one-line description>

### Out of Scope (v1)
- <Excluded feature 1>: <why excluded>
- <Excluded feature 2>: <why excluded>

### Future Considerations
- <Feature that may come in v2+>
```

---

## Section 5: User Flows (REQUIRED)

Primary user journeys as numbered steps. Include the happy path and
the top 2 to 3 error paths. Use the format below, not prose paragraphs.

```markdown
## 5. User Flows

### 5.1 Happy Path: <Flow Name>
1. User navigates to <location>
2. User inputs <data>
3. System validates <what>
4. System processes <action>
5. User sees <result>

### 5.2 Error Path: <Scenario>
1. User inputs <invalid data>
2. System returns <specific error message>
3. User sees <recovery guidance>
```

---

## Section 6: Functional Requirements (REQUIRED)

The core of the PRD. Each requirement has an ID, priority, and testable
acceptance criteria. Use RFC 2119 language.

Priority levels:
- **P0 (Must Have)**: MVP fails without this.
- **P1 (Should Have)**: Important, but MVP can ship without it.
- **P2 (Nice to Have)**: Only if time permits.

```markdown
## 6. Functional Requirements

### REQ-001: <Requirement Title> [P0]
The system MUST <specific behavior>.

**Acceptance Criteria:**
- GIVEN <context> WHEN <action> THEN <expected result>
- GIVEN <context> WHEN <edge case> THEN <expected handling>

### REQ-002: <Requirement Title> [P1]
The system SHOULD <specific behavior>.

**Acceptance Criteria:**
- GIVEN <context> WHEN <action> THEN <expected result>
```

---

## Section 7: Non-Functional Requirements (REQUIRED)

Performance, security, accessibility, reliability. Each must be testable.

```markdown
## 7. Non-Functional Requirements

### NFR-001: Performance
- Page load time MUST be < 2s on 3G connection
- API response time MUST be < 500ms at p95
- Database queries MUST NOT exceed 100ms at p95

### NFR-002: Security
- All user input MUST be sanitized before storage
- Authentication tokens MUST expire after <duration>
- Sensitive data MUST be encrypted at rest

### NFR-003: Accessibility
- MUST meet WCAG 2.1 AA standards
- All interactive elements MUST be keyboard-navigable
```

---

## Section 8: Technical Architecture (REQUIRED)

Stack, data model, and integration points. Enough for an agent to make
correct architectural decisions, but not so much that it wastes tokens
repeating discoverable information.

```markdown
## 8. Technical Architecture

### 8.1 Stack
- Runtime: <Node 22 / Python 3.12 / etc.>
- Framework: <Next.js 15 / FastAPI / etc.>
- Database: <PostgreSQL 16 / SQLite / etc.>
- ORM: <Prisma / Drizzle / SQLAlchemy / etc.>
- Styling: <Tailwind CSS 4 / etc.>
- Testing: <Vitest / Pytest / etc.>

### 8.2 Data Model

<Entity definitions with fields, types, constraints, and relationships.
Use a table or code block for clarity.>

#### Entity: <Name>
| Field       | Type      | Constraints          | Description           |
|-------------|-----------|----------------------|-----------------------|
| id          | UUID      | PK, auto-generated   | Unique identifier     |
| title       | string    | NOT NULL, max 255    | Display name          |
| created_at  | timestamp | NOT NULL, default NOW | Creation timestamp    |

#### Relationships
- <Entity A> has many <Entity B>
- <Entity B> belongs to <Entity A>

### 8.3 API Contracts (CONDITIONAL: include when the feature has APIs)

For each endpoint, specify method, path, request body, response body,
and error responses with realistic example data.

#### POST /api/v1/<resource>
**Request:**
```json
{
  "title": "Example Resource",
  "category": "demo",
  "metadata": { "key": "value" }
}
```

**Response (201):**
```json
{
  "id": "res_abc123",
  "title": "Example Resource",
  "category": "demo",
  "created_at": "2026-05-12T14:30:00Z"
}
```

**Error (422):**
```json
{
  "error": "validation_error",
  "details": [
    { "field": "title", "message": "Title is required" }
  ]
}
```

### 8.4 File Structure

Explicit directory tree showing where new files go. If working in an
existing repo, show only the additions/changes, not the entire tree.

```
src/
  modules/
    <feature>/
      <feature>.controller.ts    -- Route handlers
      <feature>.service.ts       -- Business logic
      <feature>.repository.ts    -- Data access
      <feature>.types.ts         -- Types and interfaces
      <feature>.test.ts          -- Unit tests
  lib/
    validators/
      <feature>.schema.ts        -- Zod/Joi validation schemas
```
```

---

## Section 9: Migration and Data (CONDITIONAL)

Include when the feature involves database changes, data migration, or
seeding. Agents need exact SQL or ORM migration code, not descriptions.

```markdown
## 9. Migration Plan

### 9.1 Database Migrations
<Exact migration steps or SQL>

### 9.2 Data Seeding
<Seed data for development/testing>

### 9.3 Rollback Plan
<How to undo the migration safely>
```

---

## Section 10: Test Plan (REQUIRED)

What to test, how to test it, and when a module is "done."

```markdown
## 10. Test Plan

### Test Strategy
- Unit tests for all business logic (target: >80% coverage)
- Integration tests for API endpoints
- E2E tests for critical user flows

### Test Cases by Module

#### Module: <Name>
| ID      | Scenario                        | Type        | Expected Result       |
|---------|---------------------------------|-------------|-----------------------|
| TC-001  | Create resource with valid data | Integration | Returns 201 + body    |
| TC-002  | Create resource without title   | Integration | Returns 422 + error   |
| TC-003  | List resources with pagination  | Integration | Returns paginated set |

### Definition of Done
A module is complete when:
- [ ] All P0 requirements pass acceptance criteria
- [ ] All test cases pass
- [ ] No linting or type errors
- [ ] Code reviewed (or agent self-review against conventions)
```

---

## Section 11: Build Order (REQUIRED)

Numbered, dependency-sorted phases. Each phase has a clear deliverable
and a Definition of Done. Phase N never depends on Phase N+1.

This is the section agents use to sequence their work. Be precise.

```markdown
## 11. Build Order

### Phase 1: Foundation
**Deliverable:** <what exists when this phase is done>
**Tasks:**
1. <Specific task with file path>
2. <Specific task with file path>
**Definition of Done:**
- [ ] <Testable checkpoint>
- [ ] <Testable checkpoint>

### Phase 2: Core Logic
**Depends on:** Phase 1
**Deliverable:** <what exists when this phase is done>
**Tasks:**
1. <Specific task>
2. <Specific task>
**Definition of Done:**
- [ ] <Testable checkpoint>

### Phase 3: Integration and Polish
**Depends on:** Phase 1, Phase 2
**Deliverable:** <what exists when this phase is done>
**Tasks:**
1. <Specific task>
2. <Specific task>
**Definition of Done:**
- [ ] All P0 requirements pass
- [ ] Test suite green
- [ ] No TypeScript/lint errors
```

---

## Section 12: Protected Behaviors (REQUIRED)

Explicit list of things the implementation MUST NOT break. Agents lack
institutional knowledge. Without this section, they will confidently
refactor code that other systems depend on.

```markdown
## 12. Protected Behaviors

The following existing behaviors MUST NOT be altered by this
implementation:

- <Endpoint/function>: <why it is protected>
- <Data format>: <downstream consumers>
- <Authentication flow>: <dependent services>

If any protected behavior must change, stop and discuss with the user
before proceeding.
```

---

## Section 13: Open Questions (CONDITIONAL)

Include when the Discovery Interview surfaced questions that the user
could not answer yet. Mark each with an owner and a deadline.

```markdown
## 13. Open Questions

| # | Question                                | Owner   | Deadline   | Impact if Unresolved      |
|---|-----------------------------------------|---------|------------|---------------------------|
| 1 | Which payment provider for invoicing?   | @user   | 2026-05-20 | Blocks Phase 3            |
| 2 | Retention policy for audit logs?        | @user   | 2026-05-25 | Default to 90 days        |
```

---

## Section 14: Assumptions (CONDITIONAL)

Include when you made assumptions during the Discovery Interview that
the user did not explicitly confirm. Each assumption is a risk.

```markdown
## 14. Assumptions

- [ASSUMPTION] PostgreSQL 16 is the target database. If different,
  update Section 8.1 and all migration code.
- [ASSUMPTION] Authentication uses Clerk. If self-hosted auth, the
  auth middleware in Phase 1 must be rewritten.
```

---

## Formatting Rules (always apply)

1. Use ATX-style headings (`#`, `##`, `###`). No setext underlines.
2. Code blocks use triple backticks with language identifiers.
3. Tables use pipe syntax with alignment.
4. Requirements use `MUST`, `MUST NOT`, `SHOULD`, `MAY` per RFC 2119.
5. File paths are always monospaced: `src/modules/auth/auth.service.ts`.
6. JSON examples use realistic data, not `"string"` or `"example"`.
7. No filler prose. Every sentence either constrains, instructs, or
   exemplifies. If it does none of those, delete it.
8. Maximum line length: 80 characters in Markdown source for readability
   in terminals and editors.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)