Initial commit

2025-11-30 08:45:31 +08:00
commit ca9b85ccda
35 changed files with 10784 additions and 0 deletions
--- a/skills/spec-author/guides/technical-requirement.md
+++ b/skills/spec-author/guides/technical-requirement.md
@@ -0,0 +1,382 @@
+# How to Create a Technical Requirement Specification
+
+Technical Requirements (PRD or TRQ) translate business needs into specific, implementation-ready technical requirements. They bridge the gap between "what we want to build" (business requirements) and "how we'll build it" (design documents).
+
+## Quick Start
+
+```bash
+# 1. Create a new technical requirement
+scripts/generate-spec.sh technical-requirement prd-001-descriptive-slug
+
+# 2. Open and fill in the file
+# (The file will be created at: docs/specs/technical-requirement/prd-001-descriptive-slug.md)
+
+# 3. Fill in the sections, then validate:
+scripts/validate-spec.sh docs/specs/technical-requirement/prd-001-descriptive-slug.md
+
+# 4. Fix any issues, then check completeness:
+scripts/check-completeness.sh docs/specs/technical-requirement/prd-001-descriptive-slug.md
+```
+
+## When to Write a Technical Requirement
+
+Use a Technical Requirement when you need to:
+- Define specific technical implementation details for a feature
+- Map business requirements to technical solutions
+- Document design decisions and their rationale
+- Create acceptance criteria that engineers can test against
+- Specify external dependencies and constraints
+
+## Research Phase
+
+Before writing, do your homework:
+
+### 1. Research Related Specifications
+Look for upstream and downstream specs:
+```bash
+# Find the business requirement this fulfills
+grep -r "brd\|business" docs/specs/ --include="*.md" | head -20
+
+# Find any existing technical requirements in this domain
+grep -r "prd\|technical" docs/specs/ --include="*.md" | head -20
+
+# Find design documents that might inform this
+grep -r "design\|architecture" docs/specs/ --include="*.md" | head -20
+```
+
+### 2. Research External Documentation
+Research relevant technologies and patterns:
+
+```bash
+# For external libraries/frameworks:
+# Use the doc tools to get latest official documentation
+# Example: research React hooks if implementing a frontend component
+# Example: research database indexing strategies if working with large datasets
+```
+
+Ask yourself:
+- What technologies are most suitable for this?
+- Are there industry standards we should follow?
+- What does the existing codebase use for similar features?
+- Are there performance benchmarks or best practices we should know about?
+
+### 3. Review the Codebase
+- How have similar features been implemented?
+- What patterns does the team follow?
+- What libraries/frameworks are already in use?
+- Are there existing utilities or services we can reuse?
+
+## Structure & Content Guide
+
+### Title & Metadata
+- **Title**: Clear, specific requirement (e.g., "Implement Real-Time Notification System")
+- **Priority**: critical | high | medium | low
+- **Document ID**: Use format `PRD-XXX-slug` (e.g., `PRD-001-export-api`)
+
+### Description Section
+Answer: "What technical problem are we solving?"
+
+Describe:
+- The technical challenge you're addressing
+- Why this particular approach matters
+- Current technical gaps
+- How this impacts system architecture or performance
+
+Example:
+```
+Currently, bulk exports run synchronously, blocking requests for up to 30 seconds.
+This causes timeout errors for exports > 100MB. We need an asynchronous export
+system that handles large datasets efficiently.
+```
+
+### Business Requirements Addressed Section
+Reference the business requirements this fulfills:
+```
+- [BRD-001] Bulk User Data Export - This implementation enables the export feature
+- [BRD-002] Enterprise Data Audit - This provides the data integrity requirements
+```
+
+Link each BRD to how your technical solution addresses it.
+
+### Technical Requirements Section
+List specific, measurable technical requirements:
+
+```markdown
+1. **[TR-001] Asynchronous Export Processing**
+   - Exports must complete within 5 minutes for datasets up to 500MB
+   - Must not block HTTP request threads
+   - Must handle job queue with at least 100 concurrent exports
+
+2. **[TR-002] Data Format Support**
+   - Support CSV, JSON, and Parquet formats
+   - All formats must preserve data types accurately
+   - Handle special characters and encodings (UTF-8, etc.)
+
+3. **[TR-003] Resilience & Retries**
+   - Failed exports must retry up to 3 times with exponential backoff
+   - Incomplete exports must be resumable or cleanly failed
+```
+
+**Tips:**
+- Be specific: Use numbers, formats, standards
+- Make it testable: Each requirement should be verifiable
+- Reference technical specs: Link to API contracts, data models, etc.
+- Include edge cases: What about edge cases or error conditions?
+
+### Implementation Approach Section
+Describe the high-level technical strategy:
+
+```markdown
+**Architecture Pattern**
+We'll use a job queue pattern with async workers. HTTP requests will create
+an export job and return immediately. Workers process jobs asynchronously
+and notify users when complete.
+
+**Key Technologies**
+- Job Queue: Redis with Bull library
+- Export Service: Node.js worker process
+- Storage: S3 for export files
+- Notifications: Email service
+
+**Integration Points**
+- Integrates with existing User Service API
+- Uses auth middleware for permission checking
+- Publishes completion events to event bus
+```
+
+### Key Design Decisions Section
+Document important choices:
+
+```markdown
+**Decision 1: Asynchronous Export vs. Synchronous**
+- **Decision**: Use async job queue instead of blocking requests
+- **Rationale**: Synchronous approach causes timeouts for large exports;
+  async improves reliability and user experience
+- **Tradeoffs**: Adds complexity (job queue, worker processes, status tracking)
+  but enables exports for datasets up to 500MB vs. 50MB limit
+```
+
+**Why this matters:**
+- Explains the "why" behind technical choices
+- Helps future developers understand constraints
+- Documents tradeoffs explicitly
+
+### Technical Acceptance Criteria Section
+Define how you'll know this is implemented correctly:
+
+```markdown
+### [TAC-001] Export Job Creation
+**Description**: When a user requests an export, a job is created and queued
+**Verification**: Unit test verifies job is created with correct parameters;
+  integration test verifies job appears in queue
+
+### [TAC-002] Async Processing
+**Description**: Export job completes without blocking HTTP request
+**Verification**: Load test shows HTTP response time < 100ms regardless of
+  export size; export job completes within target time
+
+### [TAC-003] Export Format Accuracy
+**Description**: Exported data matches source data exactly (no data loss)
+**Verification**: Property-based tests verify format accuracy for various
+  data types and edge cases
+```
+
+**Tips for Acceptance Criteria:**
+- Each should be testable (unit test, integration test, or manual test)
+- Include both happy path and edge cases
+- Reference specific metrics or standards
+
+### Dependencies Section
+
+**Technical Dependencies**
+- What libraries, services, or systems must be in place?
+- What versions are required?
+- What's the risk if a dependency is unavailable?
+
+```markdown
+- **Redis** (v6.0+) - Job queue | Risk: Medium
+- **Bull** (v3.0+) - Queue library | Risk: Low
+- **S3** - Export file storage | Risk: Low
+- **Email Service API** - User notifications | Risk: Medium
+```
+
+**Specification Dependencies**
+- What other specs must be completed first?
+- Why is this a blocker?
+
+```markdown
+- [API-001] Export Endpoints - Must be designed before implementation
+- [DATA-001] User Data Model - Need schema for understanding export structure
+```
+
+### Constraints Section
+Document technical limitations:
+
+```markdown
+**Performance**
+- Exports must complete within 5 minutes
+- p95 latency for export requests must be < 100ms
+- System must handle 100 concurrent exports
+
+**Scalability**
+- Support up to 500MB export files
+- Handle 1000+ daily exports
+
+**Security**
+- Only export user's own data (auth-based filtering)
+- Encryption for files in transit and at rest
+- Audit logs for all exports
+
+**Compatibility**
+- Support all major browsers (Chrome, Firefox, Safari, Edge)
+- Works with existing authentication system
+```
+
+### Implementation Notes Section
+
+**Key Considerations**
+What should the implementation team watch out for?
+
+```markdown
+**Error Handling**
+- Handle network interruptions during export
+- Gracefully fail if S3 becomes unavailable
+- Provide clear error messages to users
+
+**Testing Strategy**
+- Unit tests for export formatting logic
+- Integration tests for job queue and workers
+- Load tests for concurrent export handling
+- Property-based tests for data accuracy
+```
+
+**Migration Strategy** (if applicable)
+- How do we transition from old to new system?
+- What about existing data or users?
+
+## Writing Tips
+
+### Make Requirements Testable
+- ❌ Bad: "Export should be fast"
+- ✅ Good: "Export must complete within 5 minutes for datasets up to 500MB, with p95 latency under 100ms"
+
+### Be Specific About Trade-offs
+- Don't just say "we chose Redis"
+- Explain: "We chose Redis over RabbitMQ because it's already in our stack and provides the job persistence we need"
+
+### Link to Other Specs
+- Reference business requirements this fulfills: `[BRD-001]`
+- Reference data models: `[DATA-001]`
+- Reference API contracts: `[API-001]`
+- Reference design documents: `[DES-001]`
+
+### Document Constraints Clearly
+- Performance targets with specific numbers
+- Scalability limits and assumptions
+- Security and compliance requirements
+- Browser/platform support
+
+### Include Edge Cases
+- What happens with extremely large datasets?
+- How do we handle special characters, encoding issues, missing data?
+- What about rate limiting and concurrent requests?
+
+### Complete All TODOs
+- Replace placeholder text with actual decisions
+- If something is still undecided, explain what needs to happen to decide
+
+## Validation & Fixing Issues
+
+### Run the Validator
+```bash
+scripts/validate-spec.sh docs/specs/technical-requirement/prd-001-your-spec.md
+```
+
+### Common Issues & Fixes
+
+**Issue**: "Missing Technical Acceptance Criteria"
+- **Fix**: Add 3-5 criteria describing how you'll verify implementation correctness
+
+**Issue**: "TODO items in Implementation Approach (2 items)"
+- **Fix**: Complete the architecture pattern, technologies, and integration points
+
+**Issue**: "No Performance constraints specified"
+- **Fix**: Add specific latency, throughput, and availability targets
+
+**Issue**: "Dependencies section incomplete"
+- **Fix**: List all required libraries, services, and other specifications this depends on
+
+### Check Completeness
+```bash
+scripts/check-completeness.sh docs/specs/technical-requirement/prd-001-your-spec.md
+```
+
+## Decision-Making Framework
+
+As you write the technical requirement, reason through:
+
+1. **Problem**: What technical problem are we solving?
+   - Is this a performance issue, reliability issue, or capability gap?
+   - What's the current cost of not solving this?
+
+2. **Approach**: What are the viable technical approaches?
+   - Pros and cons of each?
+   - What's the simplest approach that solves the problem?
+   - What does the team have experience with?
+
+3. **Trade-offs**: What are we accepting with this approach?
+   - Complexity vs. flexibility?
+   - Performance vs. maintainability?
+   - Immediate need vs. future extensibility?
+
+4. **Measurability**: How will we know this works?
+   - What specific metrics define success?
+   - What's the threshold for "passing"?
+
+5. **Dependencies**: What must happen first?
+   - Are there blockers we need to resolve?
+   - Can parts be parallelized?
+
+## Example: Complete Technical Requirement
+
+```markdown
+# [PRD-001] Asynchronous Export Service
+
+**Priority:** High
+
+## Description
+Currently, bulk exports run synchronously, blocking HTTP requests for up to
+30 seconds, causing timeouts for exports > 100MB. We need an asynchronous
+export system that handles large datasets efficiently and provides job status
+tracking to users.
+
+## Business Requirements Addressed
+- [BRD-001] Bulk User Data Export - Enables the core export feature
+- [BRD-002] Enterprise Audit Requirements - Provides reliable data export
+
+## Technical Requirements
+
+1. **[TR-001] Asynchronous Processing**
+   - Export jobs must not block HTTP requests
+   - Jobs complete within 5 minutes for datasets up to 500MB
+   - System handles 100 concurrent exports
+
+2. **[TR-002] Format Support**
+   - Support CSV, JSON formats
+   - Preserve data types and handle special characters
+
+3. **[TR-003] Job Status Tracking**
+   - Users can check export job status via API
+   - Job history retained for 30 days
+
+... [rest of sections follow] ...
+```
+
+## Next Steps
+
+1. **Create the spec**: `scripts/generate-spec.sh technical-requirement prd-XXX-slug`
+2. **Research**: Find related BRD and understand the context
+3. **Fill in sections** using this guide
+4. **Validate**: `scripts/validate-spec.sh docs/specs/technical-requirement/prd-XXX-slug.md`
+5. **Fix issues** identified by validator
+6. **Share with architecture/design team** for design document creation