Systematic PRD-driven software development workflow for Claude Code.
This skill provides a complete workflow for building software applications from Product Requirements Documents (PRDs) through structured task execution and test auditing, following enterprise-grade development practices with built-in quality gates, dependency management, and traceability.
This skill contains a complete 6-phase workflow for PRD-driven development. The workflow phases are built into the skill itself and don't require separate slash command files.
To use this skill:
Invoke the skill once:
skill: prd-driven-development
Then use natural language to trigger workflow phases:
Throughout this skill documentation, you'll see commands referenced like:
@import-prds <PATH_TO_FEATURES_FILE>
@create-prd <FEATURE_DESCRIPTION|PATH>
@generate-tasks <PATH_TO_PRD_FILE>
Important: These are workflow phase triggers, NOT separate slash command files. The @ notation is just a documentation convention to clearly mark workflow phases.
You invoke them by:
/import-prds (these files don't exist)This skill works alongside existing slash commands:
Example Integration:
skill: prd-driven-development
# Creates PRD and task files
@code implement feature X
# Recognizes task file and updates it automatically
@test add coverage for authentication
# Adds tests and updates task completion status
All commands require a CLAUDE.md file at the repository root containing or linking to:
Bootstrap Process (First-Time Setup):
If CLAUDE.md is missing, the skill will automatically:
CLAUDE.md.template exists at rootCLAUDE.md[TODO: Fill this]CLAUDE.mdYou can also manually run: "Create CLAUDE.md from template and help me fill required sections"
If neither file exists: The skill will generate a basic CLAUDE.md with detected stack information and placeholders.
CLAUDE.md is the authoritative source for testing requirements:
Read CLAUDE.md Testing Strategy section FIRST
Respect explicit exclusions:
If CLAUDE.md is silent, has template text, or Testing Strategy section is incomplete:
⚠️ Default Assumption: Testing is REQUIRED
Apply test requirements based on PRD complexity:
simple complexity:
standard complexity (DEFAULT):
complex complexity:
Important: When CLAUDE.md Testing Strategy is incomplete, the workflow will:
Never skip tests due to difficulty - invest significant effort in making tests work (see Escalation Paths section below)
Lightweight Mode Triggers (automatically use simple complexity):
Examples:
✅ CLAUDE.md says: "Unit: Jest (required), Integration: Supertest (required), E2E: None (infrastructure not available)" → Skill generates unit + integration only, NO E2E tests
✅ CLAUDE.md says: "Unit: pytest, Integration: TestContainers, E2E: Playwright for critical flows" → Skill generates all three test types with diligence
✅ CLAUDE.md says: "Testing: TBD" or has generic template text → Skill applies default requirements (unit + integration mandatory, E2E for UI-backend)
Never override CLAUDE.md explicit requirements.
Define in CLAUDE.md or linked docs:
Here's a minimal example showing the complete workflow with a trivial feature: "Add /health endpoint"
skill: prd-driven-development
"Create CLAUDE.md from template"
Output: CLAUDE.md created with detected stack (Node.js from package.json)
Fill minimum sections:
"Create a PRD for: Add a /health endpoint that returns {status: 'ok', uptime: <seconds>}"
Claude asks clarifying questions:
Output: prds/0001-prd-health-endpoint.md with:
"Generate tasks from prds/0001-prd-health-endpoint.md"
Output (Phase 1 - Parent Tasks):
## Tasks
### 1.0 [ ] Create /health endpoint handler (PRD-0001-FR-1, PRD-0001-FR-2)
### 2.0 [ ] Verify performance requirements (PRD-0001-NFR-1)
Claude stops and waits: "I've generated parent tasks. Review them above. Reply 'Go' to proceed with detailed sub-tasks."
You reply: "Go"
Output (Phase 2 - Sub-Tasks):
### 1.0 [ ] Create /health endpoint handler
- [ ] 1.1 Write unit tests for health check logic (PRD-0001-FR-2)
- [ ] 1.2 Write integration test for GET /health endpoint (PRD-0001-FR-1)
- [ ] 1.3 Implement /health route handler
- [ ] 1.4 Run tests and fix failures
### 2.0 [ ] Verify performance requirements
- [ ] 2.1 Add performance test harness (PRD-0001-NFR-1)
- [ ] 2.2 Run performance tests and verify < 50ms
Also created: tasks/_index.md (global dependency tracker)
"Process task list tasks/tasks-0001-prd-health-endpoint.md"
Claude works through sub-tasks one at a time:
Sub-task 1.1 (Unit Tests):
// tests/health.test.js
describe('PRD-0001-FR-2 health check data', () => {
test('returns status ok', () => {
const data = getHealthData();
expect(data.status).toBe('ok');
});
test('returns uptime as integer', () => {
const data = getHealthData();
expect(Number.isInteger(data.uptime)).toBe(true);
});
});
Sub-task 1.2 (Integration Tests):
// tests/health.integration.test.js
describe('PRD-0001-FR-1 GET /health endpoint', () => {
test('returns 200 with JSON', async () => {
const res = await request(app).get('/health');
expect(res.status).toBe(200);
expect(res.body).toMatchObject({
status: 'ok',
uptime: expect.any(Number)
});
});
});
Sub-task 1.3 (Implementation):
// routes/health.js
app.get('/health', (req, res) => {
res.json({
status: 'ok',
uptime: Math.floor(process.uptime())
});
});
Sub-task 1.4 (Run Tests):
npm test
✓ All tests passing (2 unit, 1 integration)
Parent 1.0 Complete - Quality Gates:
npm run lint passestsc --noEmit passesnpm audit cleanCommit:
feat: add /health endpoint (PRD-0001-FR-1, PRD-0001-FR-2)
- Returns {status, uptime} as JSON
- Adds unit and integration tests
- Response time verified < 50ms
Related to PRD-0001
"Audit tests for completed features"
Output: TEST_AUDIT.md with:
.
├── CLAUDE.md
├── prds/
│ └── 0001-prd-health-endpoint.md
├── tasks/
│ ├── _index.md
│ └── tasks-0001-prd-health-endpoint.md
├── routes/
│ └── health.js
├── tests/
│ ├── health.test.js
│ └── health.integration.test.js
└── TEST_AUDIT.md
For detailed walkthrough with more complex features, see: references/quick-start-tutorial.md
Workflow Phase: Import PRDs from feature bundle
How to invoke: "Import PRDs from <PATH_TO_FEATURES_FILE>" or "Use Phase 1 to import PRDs from <PATH_TO_FEATURES_FILE>"
Use when: You have a single spec file containing multiple features.
Process:
CLAUDE.md exists with architecture baseline/prd-bundle/index.md with dependency graph and critical pathDeliverables:
/prd-bundle/index.md - Global summary and dependency graph/prd-bundle/[nn]-draft-prd-[feature-name].md - Draft PRD skeletonsNext Steps: Use Phase 2 on each draft to finalize into /prds/
Workflow Phase: Create Product Requirements Document
How to invoke: "Create a PRD for <FEATURE_DESCRIPTION>" or "Create a PRD from <PATH_TO_DRAFT>" (optional: "with complexity level: simple/standard/complex")
Complexity Profiles:
simple - Lightweight mode for UI-only features, bug fixes, scripts, config changes (minimal testing requirements)standard - Standard mode for typical features (default - unit + integration required)complex - Comprehensive mode for multi-service, data-heavy features (all test types when applicable)Process:
CLAUDE.md architecture baselinePRD-####-FR-n, PRD-####-NFR-n)/prds/[nnnn]-prd-[feature-name].mdKey PRD Sections:
Next Step: Use Phase 3 on the finalized PRD
Workflow Phase: Extend an existing PRD with new requirements
How to invoke: "Extend PRD-0001 with OAuth authentication" or "Add social login to PRD-0001"
Use when:
Smart Detection:
The workflow automatically determines if your request is:
Extension Criteria (automatic approval):
Breaking Change Criteria (suggests new PRD):
Process:
Read existing PRD file
prds/0001-prd-feature.mdprds/_index.mdAnalyze extension requirements
Update PRD file (if extension approved)
Generate incremental tasks
Update status tracking
prds/_index.md:tasks/_index.md if cross-PRD dependencies changedExample:
Before (PRD-0001 v1.0 - Complete):
## Metadata
- **PRD ID:** PRD-0001
- **Version:** 1.0
- **Status:** ✅ Complete
- **Last Updated:** 2025-01-10
## Functional Requirements
### PRD-0001-FR-1: Accept registration request
### PRD-0001-FR-2: Validate email/password
### PRD-0001-FR-3: Check duplicate email
### PRD-0001-FR-4: Create user record
### PRD-0001-FR-5: Return success response
After Extension (PRD-0001 v2.0 - In Progress):
## Metadata
- **PRD ID:** PRD-0001
- **Version:** 2.0
- **Status:** 🔄 In Progress (60% - 3/5 new tasks complete)
- **Last Updated:** 2025-01-15
## Version History
### v2.0 (2025-01-15) - OAuth Authentication Extension
- Added FR-6: OAuth login flow
- Added FR-7: Social provider integration (Google, GitHub)
- Status: 🔄 In Progress (60%)
### v1.0 (2025-01-10) - Email/Password Registration
- Initial implementation
- Status: ✅ Complete (deployed to production)
## Functional Requirements
### PRD-0001-FR-1: Accept registration request ✅
### PRD-0001-FR-2: Validate email/password ✅
### PRD-0001-FR-3: Check duplicate email ✅
### PRD-0001-FR-4: Create user record ✅
### PRD-0001-FR-5: Return success response ✅
### PRD-0001-FR-6: OAuth login flow (NEW v2.0)
### PRD-0001-FR-7: Social provider integration (NEW v2.0)
Task File Update:
### 1.0 [✅] Input Validation (v1.0)
### 2.0 [✅] Database Operations (v1.0)
### 3.0 [✅] API Endpoints (v1.0)
### 4.0 [ ] OAuth Integration (v2.0 - NEW)
- [ ] 4.1 Write unit tests for OAuth flow (PRD-0001-FR-6)
- [ ] 4.2 Write integration tests for OAuth providers (PRD-0001-FR-6)
- [ ] 4.3 Implement OAuth callback handler
- [ ] 4.4 Run tests and verify
### 5.0 [ ] Social Provider Setup (v2.0 - NEW)
- [ ] 5.1 Configure Google OAuth (PRD-0001-FR-7)
- [ ] 5.2 Configure GitHub OAuth (PRD-0001-FR-7)
- [ ] 5.3 Add provider selection UI
Status Index Update:
| PRD ID | Title | Version | Status | Completion | Tasks | Last Updated | Notes |
|--------|-------|---------|--------|------------|-------|--------------|-------|
| PRD-0001 | User Registration | 2.0 | 🔄 In Progress | 60% (3/5) | 5 | 2025-01-15 | v1.0 complete ✅, v2.0 OAuth in progress |
Deliverable:
prds/_index.md with new version and statusNext Step: Use Phase 4 to process the extended task list
Workflow Phase: Generate structured task list from PRD
How to invoke: "Generate tasks from <PATH_TO_PRD_FILE>" or "Use Phase 3 on prds/0001-prd-feature.md"
Two-Phase Process:
Phase 3.1 - Parent Tasks:
Analyze PRD and existing codebase
Extract FR/NFR IDs for traceability
Derive dependencies and generate topologically ordered parent tasks (typically 4-6 tasks)
Create tasks/tasks-[prd-name].md with parent tasks only
Present parent tasks to user with clear message:
"I've generated {N} parent tasks for this PRD. Please review them above to ensure they match your expectations."
"These parent tasks will be broken down into detailed sub-tasks (including test sub-tasks based on CLAUDE.md requirements)."
"Reply 'Go' when ready to proceed with sub-task generation, or ask for changes if needed."
STOP and WAIT for user response (required: "Go", "go", or explicit approval)
Why the wait?
Phase 3.2 - Sub-Tasks (Test-First with CLAUDE.md Authority): After user confirms "Go":
STEP 1: Parse CLAUDE.md Testing Strategy
STEP 2: Generate Test Sub-Tasks Based on CLAUDE.md
For EACH parent task, break down into sub-tasks following pattern:
If CLAUDE.md requires unit tests (or is silent):
If CLAUDE.md requires integration tests (or is silent):
If CLAUDE.md requires E2E tests AND FR involves frontend-backend (or is silent + frontend-backend): Auto-detect: login, registration, CRUD operations, chatbots, SSE, forms, etc.
E2E Framework Suggestions by Stack:
If CLAUDE.md explicitly excludes a test type:
Implementation sub-task (always included):
For database changes, add verification sub-tasks:
Only skip tests when:
Structured BLOCKED_BY_TASK Notation (REQUIRED):
When blocking a test or sub-task, use this format:
BLOCKED_BY_TASK <task-id>: <root-cause> | Mitigation: <workaround> | ETA: <date> | Owner: <person> | Safe: <yes|no|partial>
Examples:
✅ Good (structured):
test.skip('PRD-0007-FR-5 payment processing', () => {
// BLOCKED_BY_TASK 4.2: Payment gateway API not deployed to staging
// Mitigation: Using mock payment responses in local tests
// ETA: 2025-01-20 | Owner: @jane | Safe: Yes with feature flag
});
✅ Good (structured, Python):
@pytest.mark.skip(reason="BLOCKED_BY_TASK 3.1: User model migration pending | Mitigation: Using in-memory stub | ETA: Tomorrow | Owner: @bob | Safe: No - integration tests blocked")
def test_user_creation_prd_0012_fr_2():
pass
❌ Bad (unstructured):
test.skip('payment test', () => {
// BLOCKED_BY_TASK 4.2
});
Required Fields:
4.2, 0001-2.0)Yes with mitigation, No must wait, Partial limited functionality)tasks/_index.md for global dependency trackingContract-First Workflow for Blocked Dependencies:
When a sub-task depends on an incomplete upstream task, use contract-first development to avoid rewrites:
Step 1: Identify the Dependency Interface
Step 2: Define or Import the Contract
# Example: API dependency
mkdir -p contracts/
# Get contract from upstream team OR define expected interface
curl https://api-staging.example.com/openapi.yaml > contracts/auth-api-v1.yaml
# Example: Database dependency
# Reference existing schema or create expected schema
cp prisma/schema.prisma contracts/expected-user-model.prisma
Step 3: Generate Code from Contract
Step 4: Implement Against Contract with Feature Flags
// Example: Feature flag for unstable dependency
import { authClient } from './generated/auth-api-client'; // from contract
import { mockAuthClient } from './mocks/auth-client'; // mock for testing
const useRealAuth = process.env.ENABLE_REAL_AUTH === 'true'; // feature flag
export const auth = useRealAuth ? authClient : mockAuthClient;
test('PRD-0007-FR-3 user login', async () => {
// Test works with both real and mock auth
const result = await auth.login({ email, password });
expect(result.token).toBeDefined();
});
Step 5: Add Contract Sync Check
# scripts/check_contract_sync.sh
#!/bin/bash
# Compares local contract with upstream to detect breaking changes
LOCAL_CONTRACT="contracts/auth-api-v1.yaml"
REMOTE_CONTRACT="https://api-staging.example.com/openapi.yaml"
diff <(curl -s $REMOTE_CONTRACT) $LOCAL_CONTRACT
if [ $? -ne 0 ]; then
echo "⚠️ Contract mismatch detected! Upstream API changed."
echo "Update $LOCAL_CONTRACT and regenerate client code."
exit 1
fi
Step 6: Switch to Real Implementation Once upstream task completes with Readiness Proof:
// 1. Update contract file if needed
// 2. Regenerate client code: npm run generate:api-client
// 3. Enable feature flag: ENABLE_REAL_AUTH=true
// 4. Run integration tests: npm test -- --integration
// 5. Remove mock once tests pass
Contract-First Checklist:
contracts/ or linked from upstreamBenefits:
tasks/_index.md for global dependency trackingDeliverables:
Next Step: Use Phase 4 to execute tasks
Workflow Phase: Process task list systematically
How to invoke: "Process task list <PATH_TO_TASK_LIST_FILE>" or "Use Phase 4 on tasks/tasks-0001.md"
Sub-Task Level Protocol:
tasks/_index.md for dependency status (must be ready, not blocking or at-risk)BLOCKED_BY_TASK x.y with detailsANTI-PATTERNS TO AVOID: ❌ "CLAUDE.md says E2E required but tests are too hard, skipping" ❌ Commenting out failing tests without BLOCKED_BY_TASK ❌ Only writing unit tests when CLAUDE.md requires integration tests ❌ Giving up on test setup after first attempt ❌ Marking sub-task complete with failing tests ❌ Ignoring CLAUDE.md explicit exclusions and generating tests anyway
CORRECT PATTERNS: ✅ Reading CLAUDE.md Testing Strategy before generating tests ✅ Respecting explicit exclusions ("No E2E" → don't generate E2E) ✅ Investing significant effort to solve test infrastructure issues ✅ Writing all required test types per CLAUDE.md ✅ Properly documenting blocked tests with task references ✅ Researching and implementing test setup (containers, mocks, fixtures)
Parent Task Completion Protocol:
When all sub-tasks under a parent are [x]:
## Readiness Proof: API v1.2.0 contract (openapi.yaml#L45), Tests passing (CI run #123), Deployed to staging (https://api-staging.example.com/health)[x]tasks/_index.md with:ready (with readiness proof link)Database Change Detection Guide:
When Database Verification Applies: ✅ PRD includes FRs that modify database schema:
When Database Verification Does NOT Apply: ❌ Pure CRUD operations using existing schema ❌ Business logic changes with no schema impact ❌ Frontend-only changes ❌ Configuration or documentation updates
Database Environment Setup:
If migration system exists in CLAUDE.md:
If NO migration system exists:
Detect database type from CLAUDE.md or dependencies:
Create migration infrastructure:
Track current database state (CRITICAL for dev/test):
Option 1: Schema Definition File (Recommended)
schema.sql or schema.prisma with current stateOption 2: Migration Tracking Table/Collection
schema_migrations table/collectionOption 3: Declarative Models (ORM-based)
Database State Management Workflow:
1. Developer adds new feature requiring schema change
2. Update model/schema definition
3. Generate migration: `npm run migration:generate` or `alembic revision --autogenerate`
4. Review generated migration
5. Apply to dev database: `npm run migrate` or `alembic upgrade head`
6. Commit migration file + updated schema
7. CI/Test runs migrations against clean test DB
8. Current state = all migrations applied + schema file matches
For Test/Development Databases:
Test Database Setup Options (choose based on stack):
Testcontainers (recommended - Docker-based isolation)
docker-compose (manual but flexible)
docker-compose up -d test-dbnpm run migrate or equivalentdocker-compose downIn-memory database (fast but limited)
Add to CLAUDE.md when setting up:
## Data Stores
- Database: [PostgreSQL 15 | MongoDB 6 | etc.]
- Migration tool: [Alembic | Prisma | Flyway | Rails | Sequelize | etc.]
- Test environment: [Testcontainers | docker-compose test-db service]
- Quick start: `docker-compose up -d test-db && npm run migrate`
- Schema location: [migrations/ | prisma/schema.prisma | db/schema.rb]
Critical Database Verification Mindset:
OLD: Files exist = Work complete
NEW: Files exist + Executed + Verified = Work complete
Workflow Phase: Audit test quality and completeness
How to invoke:
Purpose: Dual-purpose audit that verifies BOTH test coverage AND test correctness against specifications.
Two-Phase Workflow:
Phase 5.1 - Generate Audit Report (Always - Read-Only)
TEST_AUDIT.md report with findingsPhase 5.2 - Auto-Append Missing Tests (Optional - Write) After report is generated, prompt user:
Found 3 missing tests for PRD-0001:
- Unit test for special char validation (PRD-0001-FR-3)
- Integration test for POST /signup (PRD-0001-FR-3)
- Performance test for /signup (PRD-0001-NFR-1)
Should I add these as sub-tasks to your task file?
A) Yes - Add all missing tests to tasks/tasks-0001-prd-auth.md
B) Custom - Let me choose which tests to add
C) No - Just show me the report (I'll add manually)
If approved (Option A or B):
**Added by Test Audit (YYYY-MM-DD):** annotationExample Auto-Append Output:
### 1.0 [✅] User Registration Implementation
- [✅] 1.1 Write unit tests for email validation
- [✅] 1.2 Write integration tests for POST /signup
- [✅] 1.3 Implement signup logic
- [✅] 1.4 Run tests and verify passing
**Added by Test Audit (2025-01-15):**
- [ ] 1.5 Add missing unit test for special char validation (PRD-0001-FR-3)
- [ ] 1.6 Fix incorrect email assertion in validation.test.js:42 (PRD-0001-FR-2)
### 2.0 [✅] Performance Optimization
- [✅] 2.1 Database query optimization
**Added by Test Audit (2025-01-15):**
- [ ] 2.2 Add performance test for /signup endpoint (PRD-0001-NFR-1)
Invocation Examples:
@test-audit - Report only, prompts for test type and scope@test-audit unit - Audits all unit tests, report only@test-audit unit src/features/auth - Scoped to auth folder@test-audit all completed-only with-run - Audit + execute tests for completed FRs@test-audit with-update - Report + auto-append promptKey Features:
BLOCKED_BY_TASK notationScope Options:
completed-only (default) - Audit only FRs/NFRs linked to completed tasks [x]all-tasks - Audit all FRs/NFRs in PRD (completed + pending)Run Modes:
with-run - Execute targeted tests for implemented FRs/NFRsfull-run - Execute full test suiteUpdate Modes:
with-update - Prompt to auto-append missing tests to task filesDeliverable: TEST_AUDIT.md report with:
When to Use:
Next Steps:
TEST_AUDIT.md, manually add missing tests to task filesWorkflow Phase: Generate comprehensive PRD status report
How to invoke:
Purpose: Provides at-a-glance visibility into all PRD completion states, progress tracking, and project health.
Process:
Read prds/_index.md
Generate report sections:
Apply filters (if specified):
in-progress - Show only 🔄 In Progress PRDsblocked - Show only 🚫 Blocked PRDsPRD-0001 - Show detailed status for single PRDsummary - Executive summary onlyWrite STATUS_REPORT.md
Report Sections:
1. Executive Summary
## Executive Summary
**Project Health:** On Track | At Risk | Blocked
### Overall Progress
- **Total PRDs:** 5
- **✅ Complete:** 3 (60%)
- **🔄 In Progress:** 1 (20%)
- **📋 Draft:** 1 (20%)
- **🚫 Blocked:** 0 (0%)
### Velocity
- **Completed this week:** 2 PRDs
- **Average time to complete:** 5 days
2. In Progress PRDs (Most important section)
## 🔄 In Progress PRDs
### PRD-0001: User Registration (v2.0)
- **Status:** 🔄 In Progress
- **Completion:** 60% (3/5 tasks complete)
- **Started:** 2025-01-15
- **Est. Completion:** 2025-01-18 (based on current velocity)
**Current Work:**
- [✅] 1.0 Input Validation
- [✅] 2.0 Database Operations
- [✅] 3.0 API Endpoints
- [ ] 4.0 OAuth Integration (IN PROGRESS)
- [ ] 5.0 Security Hardening
**Version History:**
- v2.0 (current): OAuth authentication extension
- v1.0 (complete): Email/password registration
**Next Steps:**
1. Complete OAuth integration (task 4.0)
2. Run security hardening (task 5.0)
3. Run test audit to validate coverage
4. Deploy to staging
3. Recently Completed PRDs
## ✅ Recently Completed (Last 30 Days)
### PRD-0002: Payment Processing (v1.0)
- **Completed:** 2025-01-10
- **Duration:** 7 days
- **Test Coverage:** 95%
4. Dependency Chain
## Dependency Chain
PRD-0001 (In Progress) 🔄
└─> PRD-0005 (Blocked - waiting on 0001)
PRD-0002 (Complete) ✅
PRD-0003 (Complete) ✅
PRD-0004 (Draft) 📋
Command Variations:
Full Report:
"Generate status report"
Generates complete STATUS_REPORT.md with all sections.
In-Progress Only:
"Status report for in-progress PRDs"
Shows only 🔄 In Progress section (useful for daily standup).
Single PRD Detail:
"Status report for PRD-0001"
Detailed breakdown of single PRD with all tasks, version history, metrics.
Summary Only:
"Status report summary"
Executive summary section only (quick health check).
Deliverable: STATUS_REPORT.md with requested scope
When to Use:
Integration with Status Index:
Status report reads from prds/_index.md (auto-maintained by workflow):
Next Step: Use insights from report to prioritize work, unblock dependencies, or generate new PRDs
Throughout workflow, use PRD-scoped IDs:
PRD-####-FR-nPRD-####-NFR-nFile: tasks/_index.md
Consolidates cross-PRD dependencies and task readiness with automated health tracking.
Structure:
# Global Task Dependency Index
Last Updated: [Timestamp]
Auto-generated by: @generate-tasks, @process-task-list
## Dependency Health Summary
- ✅ Ready: X tasks (0 blockers)
- ⚠️ At-Risk: Y tasks (dependency health degraded)
- 🚫 Blocked: Z tasks (waiting on prerequisites)
## Cross-PRD Dependencies
| Task ID | PRD | Description | Status | Depends On | Readiness Proof | Health | Updated |
|---------|-----|-------------|--------|------------|----------------|--------|---------|
| 0001-1.0 | 0001 | User Auth API | ✅ ready | - | [API contract](./contracts/auth-v1.yaml), [Tests](CI#123) | 🟢 healthy | 2025-01-15 |
| 0002-2.0 | 0002 | Profile Service | 🚫 blocked | 0001-1.0 | - | 🔴 waiting | 2025-01-14 |
| 0003-1.0 | 0003 | Notification API | ⚠️ at-risk | 0001-1.0 | - | 🟡 contract changed | 2025-01-15 |
## Recommended Execution Order (Topological Sort)
**How to determine which task to work on first:**
1. **No dependencies** → Start immediately (these are "entry points")
2. **Has dependencies** → Wait until all prerequisite tasks are `ready` with readiness proof
3. **Critical path** → Longest chain of dependent tasks (prioritize to avoid delays)
**Example from table above:**
**Execution Order:**
1. ✅ **Start: 0001-1.0** (no dependencies)
2. ⏸️ **Wait: 0002-2.0** (blocked by 0001-1.0)
3. ⏸️ **Wait: 0003-1.0** (blocked by 0001-1.0)
**After 0001-1.0 completes:**
4. ✅ **Start: 0002-2.0** (dependency now ready)
5. ✅ **Start: 0003-1.0** (dependency now ready) — can work in parallel with 0002-2.0
**Critical Path:** 0001-1.0 → 0002-2.0 (longest chain = 2 tasks)
**Decision Guide:**
- If multiple tasks are ready (no blockers), prioritize:
1. Tasks on the critical path (longest dependency chain)
2. Tasks that unblock the most downstream work
3. Tasks with earliest deadlines or highest business value
## Status Definitions
- **✅ ready:** All gates passed, readiness proof provided, consumers can proceed
- **⚠️ at-risk:** Completed but readiness proof stale/incomplete, or dependency changed
- **🚫 blocked:** Depends on tasks that are not ready
## Health Indicators
- **🟢 healthy:** Readiness proof valid, no changes since last check
- **🟡 contract changed:** API/schema/interface modified, consumers may need updates
- **🟠 tests failing:** Dependency tests currently failing, instability risk
- **🔴 waiting:** Prerequisite not ready, cannot proceed
## Blockers Detail
### Task 0002-2.0: Profile Service
- **Blocked by:** 0001-1.0 (User Auth API)
- **Root cause:** Auth API not deployed to staging
- **Mitigation:** Using mock auth in local tests
- **ETA:** 2025-01-16 (in 1 day)
- **Owner:** @jane
- **Safe to proceed:** ⚠️ Yes with feature flag `enable_real_auth=false`
### Task 0003-1.0: Notification API
- **Blocked by:** 0001-1.0 (User Auth API)
- **Root cause:** Auth contract changed (userId field renamed to userUuid)
- **Mitigation:** Update contract import to auth-v1.1.yaml
- **ETA:** Today
- **Owner:** @bob
- **Safe to proceed:** ✅ Yes, contract synced
Update Triggers:
@generate-tasks creates/updates this file with initial dependencies@process-task-list updates status when tasks completenpm run deps:check or python scripts/check_deps.py for health validationAutomation Scripts (recommended):
Create scripts/check_task_deps.sh or scripts/check_deps.py:
#!/bin/bash
# Validates readiness proofs and updates health indicators
# - Checks if API contract files exist
# - Pings health check URLs
# - Verifies test reports are recent
# - Updates health column in tasks/_index.md
CI Integration:
# .github/workflows/dep-check.yml
name: Dependency Health Check
on: [push, pull_request]
jobs:
check-deps:
runs-on: ubuntu-latest
steps:
- run: npm run deps:check || python scripts/check_deps.py
- name: Comment PR if blockers found
if: failure()
run: gh pr comment --body "⚠️ Blocked tasks detected. See tasks/_index.md"
The workflow enforces "make effort" principles, but sometimes you genuinely get stuck. Here's the escalation protocol:
Escalation Protocol:
First 30 Minutes: Research & Debug
After 30 Minutes: Ask for Clarification
Error: Database connection refused"Decision Point: Continue, Defer, or Adapt
BLOCKED_BY_TASK notationDocument Resolution
✅ Acceptable:
## Deferred/Skipped Tests
- `tests/integration/payment.int.test.ts` - BLOCKED_BY_TASK 4.2: Payment gateway API not deployed to test environment | Mitigation: Using mock payment service | ETA: 2025-01-20 | Owner: @infra-team | Safe: Yes with feature flag `use_real_payments=false`
❌ Unacceptable:
# Skipped integration tests because Testcontainers is hard to set up
Escalation Protocol:
Check for Template Text
[Tool name] or [Framework(s)] placeholders → needs fillingPrompt for Clarification
Update CLAUDE.md
Escalation Protocol:
Detect Missing Infrastructure
Propose Solution
Create Infrastructure Task (if Option B)
BLOCKED_BY_TASK 0.0Escalation Protocol:
Identify Ambiguity
Ask Clarifying Questions
Update PRD with Answers
Escalation Protocol:
Check tasks/_index.md
ready but no readiness proof linkPrompt for Verification
contracts/auth-v1.yaml)"https://auth-staging.example.com/health)"BLOCKED_BY_TASK 1.0 until available?"Decision
| Issue | Likely Cause | Solution | See Section |
|---|---|---|---|
| Tests failing | Infrastructure/setup | Research → Ask → Document | Scenario 1 |
| CLAUDE.md unclear | Template not filled | Prompt for clarification → Update | Scenario 2 |
| No migration tool | First DB change | Propose tool → Add infrastructure task | Scenario 3 |
| Ambiguous PRD | Incomplete requirements | Ask questions → Update PRD | Scenario 4 |
| Blocked by dependency | Missing readiness proof | Request proof → Use contracts | Scenario 5 |
| Can't find files | Wrong directory/path | Check codebase structure → Ask | Troubleshooting Guide |
For detailed troubleshooting, see: references/troubleshooting.md
[x]DoD Validation Checklist:
First, invoke the skill:
skill: prd-driven-development
Then use natural language for each phase:
pytest path/to/test.py -k PRD_0007_FR_3npx jest path/to/test.ts -t "PRD-0007-FR-3"go test ./... -run PRD_0007_FR_3See references/commands-guide.md for complete command documentation, all test frameworks, quality gates, and batch execution modes.