@dtt_siye/atool 1.1.0

package/skills/requirements-writer/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: requirements-writer
+description: Guide users through a structured workflow for writing PRDs and requirements documents. Use when user wants to write Product Requirements Documents (PRD), Functional Requirements (FR), Non-Functional Requirements (NFR), Acceptance Criteria (AC), or User Stories. This workflow implements a phased approach to avoid context length limitations: 1) Create requirements outline and plan, 2) Write detailed PRDs by module/feature, 3) Write comprehensive User Stories (8000+ words each) with complete specs.
+version: 1.0.0
+allowed-tools: Read, Write, Edit, Bash, Skill
+---
+
+# Requirements Writer
+
+Guide for writing comprehensive Product Requirements Documents (PRD), Functional Requirements (FR), Non-Functional Requirements (NFR), Acceptance Criteria (AC), and User Stories following Inspection Agent project standards.
+
+## Purpose
+
+Ensure requirements documentation is:
+- **Business-readable** - Clear to non-technical stakeholders
+- **Testable** - Can be verified through acceptance criteria
+- **Traceable** - Linked from PRD → FR → US → AC → Design → Implementation
+
+This skill uses a **phased approach** to avoid context length limitations and ensure consistency:
+1. **Requirements Outline & Plan** - High-level structure and module breakdown
+2. **Module-Level PRDs** - Detailed requirements by functional module
+3. **User Stories** - Comprehensive specifications (8000+ words each)
+
+## When This Skill Activates
+
+This skill activates when:
+- Writing or updating PRDs (Product Requirements Documents)
+- Creating Functional Requirements (FR) or Non-Functional Requirements (NFR)
+- Defining Acceptance Criteria (AC)
+- Writing User Stories (US)
+- Explicitly invoked via "write PRD", "create requirements", or similar phrases
+
+## Critical Dependencies
+
+This skill **depends on** `doc-standards-enforcer` skill:
+- All documents must follow file naming: `<x-digit-id>-<slug>.md`
+- All documents must include frontmatter template
+- All documents must include version history table
+- All documents must be in appropriate hundreds-based directory
+
+## Workflow Phases
+
+### Phase 1: Requirements Outline & Plan
+
+**Objective**: Create high-level structure to guide detailed writing and avoid context issues.
+
+**Deliverables**:
+- Requirements outline document (`docs/xxx-requirements/xxx-prd-outline.md`)
+- Module breakdown with sequencing
+- Writing plan with dependencies
+
+**Template**: See `templates/prd-outline-template.md`
+
+**Key Activities**:
+1. Define project scope (In/Out)
+2. Identify modules (e.g., COMPARE, JURY, PORTAL, DETECTORS, AUTO_FIX)
+3. Create module dependency graph
+4. Establish writing sequence (start with independent modules)
+5. Define personas and scenarios
+
+### Phase 2: Module-Level PRDs
+
+**Objective**: Write detailed PRDs for each module following the outline.
+
+**Deliverables**:
+- Module PRD files (`docs/xxx-requirements/xxx-prd-<module>.md`)
+- FR/NFR documents for each module
+- Acceptance criteria for each feature
+
+**Template**: See `templates/module-prd-template.md`
+
+**Per-Module PRD Must Include**:
+- Problem/Goal
+- Scope (In/Out for this module)
+- Personas & Scenarios (relevant to module)
+- Functional Requirements (FR-<MODULE>-<SEQ>)
+- Non-Functional Requirements (NFR-<MODULE>-<SEQ>)
+- UX Notes (interaction intent, not implementation)
+- Acceptance Criteria (AC-<MODULE>-<SEQ>)
+- Risks/Assumptions
+- Cross-references to related modules
+- Version History
+
+**Writing Guidelines**:
+- One PRD per module
+- If PRD exceeds 8-12 pages, create sub-topic PRDs with an index
+- Link FRs to specific User Stories
+- NFRs must be quantifiable and testable
+- ACs must avoid subjective language (e.g., "fast", "good experience")
+- Reference data structures, APIs, and design docs
+
+### Phase 3: User Stories
+
+**Objective**: Write comprehensive User Stories with complete specifications.
+
+**Deliverables**:
+- User Story files (`docs/xxx-requirements/xxx-user-stories/xxx-us-<module>-<feature>.md`)
+- Complete spec for each US (8000+ words)
+- Detailed acceptance criteria
+- Data and metrics references
+- Permission and audit requirements
+
+**Template**: See `templates/user-story-template.md`
+
+**Per-User Story Must Include**:
+
+#### Frontmatter
+```yaml
+---
+doc_id: US-XXX-xxxx
+title: User Story Title
+status: draft
+owner: PM
+last_updated: YYYY-MM-DD
+related_docs:
+  - docs/x00-requirements/xxx-prd-<module>.md
+us_id: US-IA-0001
+module: IA
+priority: P0|P1|P2
+---
+```
+
+#### Story Statement
+```
+As a [role],
+I want [feature/capability],
+so that [benefit/value].
+```
+
+#### Comprehensive Spec (8000+ Words Total)
+
+1. **Background & Context** (1000-1500 words)
+   - Business problem
+   - Current state (if any)
+   - Why this matters now
+   - Success metrics
+
+2. **User Personas & Scenarios** (1000-1500 words)
+   - Primary persona details
+   - Secondary personas (if applicable)
+   - Detailed scenario walkthroughs
+   - Edge cases and alternative paths
+
+3. **Functional Requirements** (1500-2000 words)
+   - Complete feature breakdown
+   - Input specifications
+   - Processing rules
+   - Output specifications
+   - Error handling and edge cases
+   - Integration points
+
+4. **User Experience & Interaction** (1000-1500 words)
+   - UI/UX flow descriptions
+   - Interaction patterns
+   - Feedback mechanisms
+   - Accessibility considerations
+   - Responsive behavior
+
+5. **Data & Metrics** (800-1000 words)
+   - Data entities involved
+   - Fields and validations
+   - Metrics to track
+   - Analytics requirements
+   - References to data dictionary
+
+6. **Permissions & Security** (800-1000 words)
+   - RBAC requirements
+   - Data scope (which data users can access)
+   - Audit requirements
+   - Privacy considerations
+   - Compliance needs
+
+7. **Acceptance Criteria** (1000-1500 words)
+   - Detailed acceptance criteria
+   - Each criterion must be objectively verifiable
+   - Test cases for each criterion
+   - Performance criteria (if applicable)
+   - Edge case coverage
+
+8. **Dependencies & Integration** (500-800 words)
+   - Legacy system dependencies
+   - New system dependencies
+   - Third-party integrations
+   - API dependencies
+   - Data migration needs (if any)
+
+9. **Risks & Mitigation** (500-800 words)
+   - Technical risks
+   - Business risks
+   - Mitigation strategies
+   - Rollback plans
+
+10. **Out of Scope** (300-500 words)
+    - Explicitly list what's NOT included
+    - Future phases
+    - Related features not in this US
+
+#### Version History Table
+```markdown
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v0.1 | YYYY-MM-DD | PM | Initial version |
+```
+
+## Validation Checklist
+
+### Phase 1: Outline Validation
+- [ ] File follows naming convention: `xxx-prd-outline.md`
+- [ ] Document includes complete frontmatter
+- [ ] All modules are identified with clear boundaries
+- [ ] Module dependencies are mapped
+- [ ] Writing sequence is defined
+- [ ] Personas are defined
+- [ ] Version history table included
+
+### Phase 2: PRD Validation
+- [ ] File follows naming convention: `xxx-prd-<module>.md`
+- [ ] Document follows doc-standards-enforcer compliance
+- [ ] Problem/Goal clearly stated
+- [ ] Scope (In/Out) defined
+- [ ] FRs follow format: `FR-<MODULE>-<SEQ>`
+- [ ] NFRs are quantifiable
+- [ ] ACs are objectively verifiable
+- [ ] Cross-references use relative paths
+- [ ] Technical details delegated to design/architecture docs
+- [ ] Version history table included
+
+### Phase 3: User Story Validation
+- [ ] File follows naming convention: `xxx-us-<module>-<feature>.md`
+- [ ] Document follows doc-standards-enforcer compliance
+- [ ] Complete frontmatter with `us_id`, `module`, `priority`
+- [ ] Story statement follows format
+- [ ] Total content is 8000+ words
+- [ ] All 10 sections are complete
+- [ ] Acceptance criteria are objectively verifiable
+- [ ] Data references link to `docs/500-data/`
+- [ ] Permission references link to security docs
+- [ ] Audit requirements specified for critical operations
+- [ ] Version history table included
+
+## How to Use This Skill
+
+### Starting a New PRD
+
+When you need to write a PRD, this skill will guide you through:
+
+1. **Automatic activation**: Mention "write PRD", "create requirements", or similar
+2. **Phase 1**: Start with requirements outline
+3. **Validation**: Review outline before proceeding
+4. **Phase 2**: Write module-level PRDs sequentially
+5. **Validation**: Review each PRD before moving to next module
+6. **Phase 3**: Write comprehensive User Stories
+7. **Final validation**: Ensure all US meet 8000+ word requirement
+
+### Example Workflow
+
+```
+User: "I need to write a PRD for the COMPARE module"
+
+Assistant: (This skill activates)
+"Let's start by creating a requirements outline. First, I'll need to understand:
+1. What is the overall project scope?
+2. What modules are involved?
+3. What are the key dependencies?
+
+Then we'll create:
+- docs/300-requirements/301-prd-outline.md
+- docs/300-requirements/311-prd-compare.md
+- docs/300-requirements/330-user-stories/331-us-compare-*.md"
+```
+
+## Integration with Doc-Standards-Enforcer
+
+This skill **automatically invokes** `doc-standards-enforcer` to ensure:
+
+1. **File naming**: All files follow `<3-digit-id>-<slug>.md` pattern
+2. **Frontmatter**: All documents have complete frontmatter
+3. **Directory structure**: Files are in correct hundreds-based directories
+4. **Status values**: Use `draft|review|approved|deprecated`
+5. **Version history**: All documents have version history table
+6. **Cross-references**: Use relative paths from repository root
+
+## Templates
+
+### Available Templates
+
+1. **PRD Outline Template**: `templates/prd-outline-template.md`
+   - Use for Phase 1: Requirements planning
+
+2. **Module PRD Template**: `templates/module-prd-template.md`
+   - Use for Phase 2: Module-level requirements
+
+3. **User Story Template**: `templates/user-story-template.md`
+   - Use for Phase 3: Comprehensive US specifications
+
+### Template Usage
+
+Templates include:
+- Complete frontmatter
+- Section placeholders with guidance
+- Required fields highlighted
+- Example content structure
+- Validation reminders
+
+## Common Mistakes to Avoid
+
+### PRD Writing
+1. **Mixing business and technical**: PRDs should focus on "what", not "how"
+2. **Vague requirements**: Requirements must be specific and testable
+3. **Missing NFRs**: Forgetting performance, security, scalability
+4. **Subjective ACs**: Using "good experience", "fast" instead of measurable criteria
+5. **No scope boundaries**: Not defining what's out of scope
+
+### User Story Writing
+1. **Insufficient detail**: Not reaching 8000+ word requirement
+2. **Missing sections**: Skipping required sections
+3. **Vague acceptance criteria**: Criteria that can't be objectively verified
+4. **No data references**: Not specifying data structures and fields
+5. **Missing security/audit**: Forgetting RBAC and audit requirements
+6. **Incomplete edge cases**: Not covering error scenarios
+
+## Writing Quality Standards
+
+### PRD Quality
+- **Clarity**: Non-technical stakeholders can understand
+- **Completeness**: All functional and non-functional requirements covered
+- **Consistency**: No contradictions within or across documents
+- **Traceability**: Each requirement links to User Story and AC
+
+### User Story Quality
+- **Comprehensive**: All 10 sections thoroughly covered (8000+ words)
+- **Testable**: Every acceptance criterion can be verified
+- **Data-aware**: All data structures referenced and defined
+- **Security-aware**: RBAC, data scope, and audit requirements specified
+- **Integration-aware**: Dependencies and integration points documented
+
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v1.0.0 | 2026-01-09 | Claude Code | Initial skill implementation with phased workflow approach |

package/skills/requirements-writer/examples/prd-outline-example.md

@@ -0,0 +1,217 @@
+---
+doc_id: PRD-OUTLINE-0301
+title: Requirements Outline - Inspection Agent Comparison Module
+status: draft
+owner: PM
+last_updated: 2026-01-09
+related_docs:
+  - docs/100-standards/102-requirements-standards.md
+  - docs/200-product/201-project-brief.md
+---
+
+## Purpose
+
+This document provides the high-level outline and writing plan for the Inspection Agent Comparison Module PRD. It defines the module breakdown, dependencies, and sequencing to ensure comprehensive requirements coverage.
+
+## Project Overview
+
+### Problem Statement
+Quality assurance engineers need to manually compare inspection results between different software versions, which is time-consuming and error-prone. Current tools lack automated comparison and visualization of differences.
+
+### Project Goals
+- Reduce comparison time by 80%
+- Achieve 95% accuracy in difference detection
+- Support side-by-side visualization
+- Enable export of comparison reports
+
+### High-Level Scope
+
+#### In Scope
+- Automated comparison of inspection results
+- Side-by-side diff visualization
+- Change highlighting and categorization
+- Comparison report export (PDF, CSV)
+- Historical comparison across versions
+
+#### Out of Scope
+- Root cause analysis of differences
+- Automatic remediation (handled by AUTO_FIX module)
+- Real-time monitoring (handled by DETECTORS module)
+- Multi-language inspection result formats (Phase 2)
+
+## Module Breakdown
+
+### Identified Modules
+
+1. **COMPARE** (This Module)
+   - Purpose: Compare inspection results and visualize differences
+   - Key Features: Diff algorithm, visualization, export
+
+2. **DETECTORS** (Dependency)
+   - Purpose: Generate inspection results
+   - Key Features: Rule engine, data collection
+
+3. **PORTAL** (Dependent)
+   - Purpose: User interface for all modules
+   - Key Features: Navigation, unified UI
+
+4. **JURY** (Peer)
+   - Purpose: Evaluate differences
+   - Key Features: Severity assessment, triage
+
+5. **AUTO_FIX** (Dependent)
+   - Purpose: Fix identified issues
+   - Key Features: Remediation suggestions
+
+### Module Dependency Graph
+
+```
+DETECTORS (Analysis Engine)
+    ↓
+COMPARE (Core Service)
+    ↓
+    ├── JURY (Evaluation Service)
+    │     ↓
+    └── AUTO_FIX (Remediation Service)
+
+PORTAL (UI Layer) - Depends on all services
+
+Writing Order:
+1. DETECTORS (no dependencies)
+2. COMPARE (depends on DETECTORS) ← Current focus
+3. JURY (depends on COMPARE)
+4. AUTO_FIX (depends on COMPARE, JURY)
+5. PORTAL (depends on all services)
+```
+
+## User Personas
+
+### Primary Personas
+
+1. **QA Engineer - Alex**
+   - Role: Quality Assurance Engineer
+   - Goals: Quickly validate software upgrades, catch regressions
+   - Pain Points: Manual comparison takes hours, easy to miss changes
+   - Typical Scenarios:
+     - Comparing pre/post upgrade inspection results
+     - Validating bug fixes
+     - Regression testing
+
+2. **Release Manager - Jordan**
+   - Role: Release Manager
+   - Goals: Ensure safe deployments, track changes over time
+   - Pain Points: No audit trail of changes, difficult to assess risk
+   - Typical Scenarios:
+     - Pre-deployment risk assessment
+     - Post-deployment verification
+     - Change impact analysis
+
+### Secondary Personas
+
+1. **DevOps Engineer - Casey**
+   - Role: DevOps Engineer
+   - Goals: Integrate comparison into CI/CD pipeline
+   - Pain Points: No API access, manual process only
+   - Typical Scenarios:
+     - Automated comparison in deployment pipeline
+     - Monitoring comparison results
+
+## Writing Plan
+
+### Phase 1: Requirements Outline (Current Document)
+- [x] Define project scope
+- [x] Identify modules
+- [x] Map dependencies
+- [x] Define writing sequence
+
+### Phase 2: Module-Level PRDs
+
+1. **COMPARE** (`docs/300-requirements/311-prd-compare.md`)
+   - [ ] Complete module PRD
+   - Estimated User Stories: 5
+   - Notes: Core comparison functionality
+
+2. **DETECTORS** (`docs/300-requirements/312-prd-detectors.md`)
+   - [ ] Complete module PRD
+   - Depends on: None
+   - Estimated User Stories: 4
+   - Notes: Must be completed before COMPARE
+
+3. **JURY** (`docs/300-requirements/313-prd-jury.md`)
+   - [ ] Complete module PRD
+   - Depends on: COMPARE
+   - Estimated User Stories: 3
+   - Notes: Evaluation of comparison results
+
+4. **AUTO_FIX** (`docs/300-requirements/314-prd-auto-fix.md`)
+   - [ ] Complete module PRD
+   - Depends on: COMPARE, JURY
+   - Estimated User Stories: 4
+   - Notes: Remediation based on comparison
+
+5. **PORTAL** (`docs/300-requirements/315-prd-portal.md`)
+   - [ ] Complete module PRD
+   - Depends on: All services
+   - Estimated User Stories: 6
+   - Notes: UI for all features
+
+### Phase 3: User Stories
+
+**Module: COMPARE**
+- [ ] US-COMPARE-001: Side-by-side comparison visualization
+- [ ] US-COMPARE-002: Diff algorithm and categorization
+- [ ] US-COMPARE-003: Historical comparison across versions
+- [ ] US-COMPARE-004: Comparison report export (PDF)
+- [ ] US-COMPARE-005: Comparison API for CI/CD integration
+
+**Module: DETECTORS**
+- [ ] US-DETECTORS-001: Rule engine configuration
+- [ ] US-DETECTORS-002: Data collection and storage
+- [ ] US-DETECTORS-003: Inspection result generation
+- [ ] US-DETECTORS-004: Detector performance monitoring
+
+## Deliverables Summary
+
+### Phase 1 Deliverables
+- [x] This outline document
+- [x] Module dependency map
+- [x] Writing sequence plan
+
+### Phase 2 Deliverables
+- [ ] `docs/300-requirements/311-prd-compare.md`
+- [ ] `docs/300-requirements/312-prd-detectors.md`
+- [ ] `docs/300-requirements/313-prd-jury.md`
+- [ ] `docs/300-requirements/314-prd-auto-fix.md`
+- [ ] `docs/300-requirements/315-prd-portal.md`
+
+### Phase 3 Deliverables
+- [ ] 22 User Stories across all modules (8000+ words each)
+- [ ] Located in `docs/300-requirements/330-user-stories/`
+
+## Assumptions & Risks
+
+### Assumptions
+- Inspection result format is stable and documented
+- Users have access to historical inspection data
+- Comparison can be performed within 30 seconds for typical datasets
+- Web UI is acceptable (no mobile app needed in Phase 1)
+
+### Risks
+- **Risk**: Inspection result format changes frequently
+  - **Mitigation**: Version the result format, support backward compatibility
+- **Risk**: Large datasets cause performance issues
+  - **Mitigation**: Implement pagination, streaming, and async comparison
+- **Risk**: False positives in diff detection
+  - **Mitigation**: Configurable diff thresholds, manual review workflow
+
+## References
+
+- Project Brief: `docs/200-product/201-project-brief.md`
+- Requirements Standards: `docs/100-standards/102-requirements-standards.md`
+- Documentation Standards: `docs/100-standards/101-documentation-standards.md`
+
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v0.1 | 2026-01-09 | PM | Initial requirements outline |