--- name: autospec-checklist description: "Generate YAML checklist for feature quality validation." --- # autospec-checklist This Agent Skill is generated from autospec.checklist. When the user invokes "$autospec-checklist" or "/autospec.checklist", load and follow these instructions directly. Treat the text after the skill or command name as "$ARGUMENTS". Do not route back through "autospec checklist"; this skill is the prompt for the stage. Project specs directory: ./specs ## Checklist Purpose: "Unit Tests for English" **CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. **NOT for verification/testing**: - NOT "Verify the button clicks correctly" - NOT "Test error handling works" - NOT "Confirm the API returns 200" - NOT checking if code/implementation matches the spec **FOR requirements quality validation**: - "Are visual hierarchy requirements defined for all card types?" (completeness) - "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) - "Are hover state requirements consistent across all interactive elements?" (consistency) - "Are accessibility requirements defined for keyboard navigation?" (coverage) - "Does the spec define what happens when logo image fails to load?" (edge cases) **Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. ## User Input ```text $ARGUMENTS ``` You **MUST** consider the user input before proceeding (if not empty). ## Pre-computed Context The following paths have been pre-computed and are available for use: - **FEATURE_DIR**: `{{.FeatureDir}}` - **FEATURE_SPEC**: `{{.FeatureSpec}}` ## Execution Steps 1. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions. They MUST: - Be generated from the user's phrasing + extracted signals from spec/plan/tasks - Only ask about information that materially changes checklist content - Be skipped individually if already unambiguous in `$ARGUMENTS` - Prefer precision over breadth Generation algorithm: 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team") 2. Cluster signals into candidate focus areas (max 4) ranked by relevance 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries 5. Formulate questions from these archetypes: - Scope refinement (e.g., "Should this include integration touchpoints?") - Risk prioritization (e.g., "Which risk areas need mandatory gating checks?") - Depth calibration (e.g., "Lightweight sanity list or formal release gate?") - Audience framing (e.g., "Author-only or peer PR review?") Defaults when interaction impossible: - Depth: Standard - Audience: Reviewer (PR) if code-related; Author otherwise - Focus: Top 2 relevance clusters 2. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: - Derive checklist theme (e.g., security, review, deploy, ux) - Consolidate explicit must-have items mentioned by user - Map focus selections to category scaffolding 3. **Load feature context**: Read from the feature directory: - spec.yaml: Feature requirements and scope - plan.yaml if exists: Technical details, dependencies, data model, API contracts - tasks.yaml if exists: Implementation tasks 4. **Generate checklist.yaml** - Create "Unit Tests for Requirements": ```yaml checklist: feature: "" branch: "" spec_path: "" domain: "" audience: "" depth: "" categories: - name: "Requirement Completeness" description: "Are all necessary requirements documented?" items: - id: "CHK001" description: "Are all functional requirements specified for the primary user flow?" quality_dimension: "completeness" spec_reference: "FR-001" # or null if checking for gap status: "pending" # pending | pass | fail notes: "" - id: "CHK002" description: "Are error handling requirements defined for all API failure modes?" quality_dimension: "completeness" spec_reference: null status: "pending" notes: "" - name: "Requirement Clarity" description: "Are requirements specific and unambiguous?" items: - id: "CHK003" description: "Is 'fast loading' quantified with specific timing thresholds?" quality_dimension: "clarity" spec_reference: "NFR-001" status: "pending" notes: "" - name: "Requirement Consistency" description: "Do requirements align without conflicts?" items: - id: "CHK004" description: "Are navigation requirements consistent across all pages?" quality_dimension: "consistency" spec_reference: "FR-010" status: "pending" notes: "" - name: "Acceptance Criteria Quality" description: "Are success criteria measurable?" items: - id: "CHK005" description: "Can all success criteria be objectively verified?" quality_dimension: "measurability" spec_reference: "SC-001" status: "pending" notes: "" - name: "Scenario Coverage" description: "Are all flows and cases addressed?" items: - id: "CHK006" description: "Are requirements defined for zero-state scenarios?" quality_dimension: "coverage" spec_reference: null status: "pending" notes: "" - name: "Edge Case Coverage" description: "Are boundary conditions defined?" items: - id: "CHK007" description: "Is fallback behavior specified when external services fail?" quality_dimension: "edge_cases" spec_reference: null status: "pending" notes: "" summary: total_items: passed: failed: pending: pass_rate: "" _meta: version: "1.0.0" generator: "autospec" generator_version: "" created: "" artifact_type: "checklist" ``` 5. **Write the checklist** to `{{.FeatureDir}}/checklists/.yaml` - Create `{{.FeatureDir}}/checklists/` directory if it doesn't exist - Use domain-based filename: `ux.yaml`, `api.yaml`, `security.yaml`, etc. 6. **Validate the artifact**: ```bash autospec artifact checklist {{.FeatureDir}}/checklists/.yaml ``` - If validation fails: fix schema errors (missing required fields, invalid types/enums) and retry - If validation passes: proceed to report 7. **Report**: Output: - Full path to checklist.yaml - Item count by category - Gap markers count (requirements needing attention) - Checklist domain and audience ## HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English" **WRONG** (Testing implementation): - "Verify landing page displays 3 episode cards" - "Test hover states work on desktop" - "Confirm logo click navigates home" **CORRECT** (Testing requirements quality): - "Are the exact number and layout of featured episodes specified?" [Completeness] - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] - "Are hover state requirements consistent across all interactive elements?" [Consistency] - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] ### Quality Dimensions - **completeness**: Are all necessary requirements present? - **clarity**: Are requirements unambiguous and specific? - **consistency**: Do requirements align with each other? - **measurability**: Can requirements be objectively verified? - **coverage**: Are all scenarios/edge cases addressed? - **edge_cases**: Are boundary conditions defined? ### ABSOLUTELY PROHIBITED - Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior - References to code execution, user actions, system behavior - "Displays correctly", "works properly", "functions as expected" - "Click", "navigate", "render", "load", "execute" - Test cases, test plans, QA procedures - Implementation details (frameworks, APIs, algorithms) ### REQUIRED PATTERNS - "Are [requirement type] defined/specified/documented for [scenario]?" - "Is [vague term] quantified/clarified with specific criteria?" - "Are requirements consistent between [section A] and [section B]?" - "Can [requirement] be objectively measured/verified?" - "Are [edge cases/scenarios] addressed in requirements?" - "Does the spec define [missing aspect]?"