---
name: autospec-analyze
description: "Analyze cross-artifact consistency and quality in YAML format."
---

# autospec-analyze

This Agent Skill is generated from autospec.analyze. When the user invokes "$autospec-analyze" or "/autospec.analyze",
load and follow these instructions directly. Treat the text after the skill or
command name as "$ARGUMENTS". Do not route back through "autospec analyze"; this skill
is the prompt for the stage.

Project specs directory: ./specs

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Goal

Identify inconsistencies, duplications, ambiguities, and underspecified items across the core artifacts (spec, plan, tasks) before implementation. This command MUST run only after `$autospec-tasks` has successfully produced a complete tasks file.

## Operating Constraints

**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis YAML file. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

**Constitution Authority**: The project constitution (`.autospec/constitution.yaml` or `AGENTS.md`, falling back to agent-specific file like `CLAUDE.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks.

## Pre-computed Context

The following paths have been pre-computed and are available for use:

- **FEATURE_DIR**: `{{.FeatureDir}}`
- **FEATURE_SPEC**: `{{.FeatureSpec}}`

## Execution Steps

### 1. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

**From spec.yaml**:
- Overview/Context
- Functional Requirements
- Non-Functional Requirements
- User Stories
- Edge Cases (if present)

**From plan.yaml**:
- Architecture/stack choices
- Data Model references
- Phases
- Technical constraints

**From tasks.yaml**:
- Task IDs
- Descriptions
- Phase grouping
- Parallel markers
- Referenced file paths

**From constitution**:
- Load `.autospec/constitution.yaml` or `AGENTS.md` (falling back to agent-specific file like `CLAUDE.md`) for principle validation

### 2. Build Semantic Models

Create internal representations (do not include raw artifacts in output):
- **Requirements inventory**: Each functional + non-functional requirement with a stable key
- **User story/action inventory**: Discrete user actions with acceptance criteria
- **Task coverage mapping**: Map each task to one or more requirements or stories
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements

### 3. Detection Passes (Token-Efficient Analysis)

Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.

#### A. Duplication Detection
- Identify near-duplicate requirements
- Mark lower-quality phrasing for consolidation

#### B. Ambiguity Detection
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)

#### C. Underspecification
- Requirements with verbs but missing object or measurable outcome
- User stories missing acceptance criteria alignment
- Tasks referencing files or components not defined in spec/plan

#### D. Constitution Alignment
- Any requirement or plan element conflicting with a MUST principle
- Missing mandated sections or quality gates from constitution

#### E. Coverage Gaps
- Requirements with zero associated tasks
- Tasks with no mapped requirement/story
- Non-functional requirements not reflected in tasks (e.g., performance, security)

#### F. Inconsistency
- Terminology drift (same concept named differently across files)
- Data entities referenced in plan but absent in spec (or vice versa)
- Task ordering contradictions
- Conflicting requirements

### 4. Severity Assignment

Use this heuristic to prioritize findings:
- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
- **LOW**: Style/wording improvements, minor redundancy not affecting execution order

### 5. Generate analysis.yaml

```yaml
analysis:
  branch: "<current git branch>"
  timestamp: "<ISO 8601 timestamp>"
  spec_path: "<relative path to spec file>"
  plan_path: "<relative path to plan file>"
  tasks_path: "<relative path to tasks file>"
  constitution_path: "<path to constitution or 'Not found'>"

findings:
  - id: "DUP-001"
    category: "duplication"
    severity: "HIGH"
    location: "spec.yaml:requirements.functional[2]"
    summary: "Two similar requirements for user login"
    details: "FR-002 and FR-005 both describe user authentication flow"
    recommendation: "Merge into single requirement; keep clearer phrasing"

  - id: "AMB-001"
    category: "ambiguity"
    severity: "MEDIUM"
    location: "spec.yaml:requirements.non_functional[0]"
    summary: "Vague performance requirement"
    details: "'Fast response time' lacks specific threshold"
    recommendation: "Quantify with specific metric (e.g., '<200ms p95')"

  - id: "COV-001"
    category: "coverage"
    severity: "HIGH"
    location: "spec.yaml:requirements.functional[3]"
    summary: "FR-004 has no corresponding task"
    details: "Password reset requirement not covered in tasks.yaml"
    recommendation: "Add task in User Story phase for FR-004 implementation"

  - id: "CON-001"
    category: "constitution"
    severity: "CRITICAL"
    location: "tasks.yaml:phases[2].tasks[0]"
    summary: "Missing test task before implementation"
    details: "Constitution requires test-first development"
    recommendation: "Add test task before implementation task T011"

  - id: "INC-001"
    category: "inconsistency"
    severity: "MEDIUM"
    location: "plan.yaml:data_model vs spec.yaml:key_entities"
    summary: "Entity naming mismatch"
    details: "'User' in spec but 'Account' in plan data model"
    recommendation: "Standardize naming across artifacts"

coverage:
  requirements:
    - id: "FR-001"
      has_task: true
      task_ids: ["T010", "T011"]
      notes: ""
    - id: "FR-002"
      has_task: false
      task_ids: []
      notes: "COVERAGE GAP"

  user_stories:
    - id: "US-001"
      tasks_count: 5
      coverage_status: "complete"
    - id: "US-002"
      tasks_count: 0
      coverage_status: "missing"

constitution_alignment:
  status: "PASS"  # or "FAIL" if any CRITICAL constitution issues
  violations:
    - principle: "Test-First Development"
      status: "VIOLATION"
      details: "3 implementation tasks lack preceding test tasks"

unmapped_tasks:
  - task_id: "T015"
    title: "Refactor logging"
    issue: "No corresponding requirement or story"

metrics:
  total_requirements: <number>
  total_tasks: <number>
  coverage_percentage: <number>  # requirements with >=1 task
  ambiguity_count: <number>
  duplication_count: <number>
  critical_issues: <number>
  high_issues: <number>
  medium_issues: <number>
  low_issues: <number>

summary:
  overall_status: "<PASS|WARN|FAIL>"
  blocking_issues: <number of CRITICAL issues>
  actionable_improvements: <number of HIGH/MEDIUM issues>
  ready_for_implementation: <true|false>

_meta:
  version: "1.0.0"
  generator: "autospec"
  generator_version: "<AUTOSPEC_VERSION from step 1>"
  created: "<CREATED_DATE from step 1>"
  artifact_type: "analysis"
```

### 6. Write the analysis to `{{.FeatureDir}}/analysis.yaml`

### 7. Validate the artifact

```bash
autospec artifact {{.FeatureDir}}/analysis.yaml
```
- If validation fails: fix schema errors (missing required fields, invalid types/enums) and retry
- If validation passes: proceed to report

### 8. Report Next Actions

At end of analysis, output a concise summary:
- If CRITICAL issues exist: Recommend resolving before implementation
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
- Provide explicit command suggestions for remediation

### 9. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

## Operating Principles

### Context Efficiency
- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
- **Token-efficient output**: Limit findings to 50; summarize overflow
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts

### Analysis Guidelines
- **NEVER modify source artifacts** (read-only analysis; only output is `analysis.yaml`)
- **NEVER hallucinate missing sections** (if absent, report them accurately)
- **Prioritize constitution violations** (these are always CRITICAL)
- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
- **Report zero issues gracefully** (emit success report with coverage statistics)