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

$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

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

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)

autospec-analyze

المزيد من هذا المستودع

المزيد من هذا المستودع