|
|
|
|
@@ -5,100 +5,182 @@ scripts:
|
|
|
|
|
ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
|
|
|
|
|
## User Input
|
|
|
|
|
|
|
|
|
|
User input:
|
|
|
|
|
```text
|
|
|
|
|
$ARGUMENTS
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`$ARGUMENTS
|
|
|
|
|
`
|
|
|
|
|
Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
|
|
|
|
|
You **MUST** consider the user input before proceeding (if not empty).
|
|
|
|
|
|
|
|
|
|
STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
|
|
|
|
|
## Goal
|
|
|
|
|
|
|
|
|
|
Constitution Authority: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
|
|
|
|
|
Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
|
|
|
|
|
|
|
|
|
|
Execution steps:
|
|
|
|
|
## Operating Constraints
|
|
|
|
|
|
|
|
|
|
1. Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
|
|
|
|
|
- SPEC = FEATURE_DIR/spec.md
|
|
|
|
|
- PLAN = FEATURE_DIR/plan.md
|
|
|
|
|
- TASKS = FEATURE_DIR/tasks.md
|
|
|
|
|
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
|
|
|
|
|
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
|
|
|
|
|
|
|
|
|
|
2. Load artifacts:
|
|
|
|
|
- Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).
|
|
|
|
|
- Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
|
|
|
|
|
- Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.
|
|
|
|
|
- Load constitution `/memory/constitution.md` for principle validation.
|
|
|
|
|
**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
|
|
|
|
|
|
|
|
|
|
3. Build internal semantic models:
|
|
|
|
|
- Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).
|
|
|
|
|
- User story/action inventory.
|
|
|
|
|
- Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).
|
|
|
|
|
- Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.
|
|
|
|
|
## Execution Steps
|
|
|
|
|
|
|
|
|
|
4. Detection passes:
|
|
|
|
|
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 (e.g., integration tasks before foundational setup tasks without dependency note).
|
|
|
|
|
- Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).
|
|
|
|
|
### 1. Initialize Analysis Context
|
|
|
|
|
|
|
|
|
|
5. Severity assignment heuristic:
|
|
|
|
|
- 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.
|
|
|
|
|
Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
|
|
|
|
|
|
|
|
|
|
6. Produce a Markdown report (no file writes) with sections:
|
|
|
|
|
- SPEC = FEATURE_DIR/spec.md
|
|
|
|
|
- PLAN = FEATURE_DIR/plan.md
|
|
|
|
|
- TASKS = FEATURE_DIR/tasks.md
|
|
|
|
|
|
|
|
|
|
### Specification Analysis Report
|
|
|
|
|
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
|
|
|
|
|----|----------|----------|-------------|---------|----------------|
|
|
|
|
|
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
|
|
|
|
|
(Add one row per finding; generate stable IDs prefixed by category initial.)
|
|
|
|
|
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
|
|
|
|
|
|
|
|
|
|
Additional subsections:
|
|
|
|
|
- Coverage Summary Table:
|
|
|
|
|
| Requirement Key | Has Task? | Task IDs | Notes |
|
|
|
|
|
- Constitution Alignment Issues (if any)
|
|
|
|
|
- Unmapped Tasks (if any)
|
|
|
|
|
- Metrics:
|
|
|
|
|
* Total Requirements
|
|
|
|
|
* Total Tasks
|
|
|
|
|
* Coverage % (requirements with >=1 task)
|
|
|
|
|
* Ambiguity Count
|
|
|
|
|
* Duplication Count
|
|
|
|
|
* Critical Issues Count
|
|
|
|
|
### 2. Load Artifacts (Progressive Disclosure)
|
|
|
|
|
|
|
|
|
|
7. At end of report, output a concise Next Actions block:
|
|
|
|
|
- If CRITICAL issues exist: Recommend resolving before `/implement`.
|
|
|
|
|
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions.
|
|
|
|
|
- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'".
|
|
|
|
|
Load only the minimal necessary context from each artifact:
|
|
|
|
|
|
|
|
|
|
8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
|
|
|
|
|
**From spec.md:**
|
|
|
|
|
|
|
|
|
|
Behavior rules:
|
|
|
|
|
- NEVER modify files.
|
|
|
|
|
- NEVER hallucinate missing sections—if absent, report them.
|
|
|
|
|
- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.
|
|
|
|
|
- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.
|
|
|
|
|
- If zero issues found, emit a success report with coverage statistics and proceed recommendation.
|
|
|
|
|
- Overview/Context
|
|
|
|
|
- Functional Requirements
|
|
|
|
|
- Non-Functional Requirements
|
|
|
|
|
- User Stories
|
|
|
|
|
- Edge Cases (if present)
|
|
|
|
|
|
|
|
|
|
Context: {ARGS}
|
|
|
|
|
**From plan.md:**
|
|
|
|
|
|
|
|
|
|
- Architecture/stack choices
|
|
|
|
|
- Data Model references
|
|
|
|
|
- Phases
|
|
|
|
|
- Technical constraints
|
|
|
|
|
|
|
|
|
|
**From tasks.md:**
|
|
|
|
|
|
|
|
|
|
- Task IDs
|
|
|
|
|
- Descriptions
|
|
|
|
|
- Phase grouping
|
|
|
|
|
- Parallel markers [P]
|
|
|
|
|
- Referenced file paths
|
|
|
|
|
|
|
|
|
|
**From constitution:**
|
|
|
|
|
|
|
|
|
|
- Load `/memory/constitution.md` for principle validation
|
|
|
|
|
|
|
|
|
|
### 3. Build Semantic Models
|
|
|
|
|
|
|
|
|
|
Create internal representations (do not include raw artifacts in output):
|
|
|
|
|
|
|
|
|
|
- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
|
|
|
|
|
- **User story/action inventory**: Discrete user actions with acceptance criteria
|
|
|
|
|
- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
|
|
|
|
|
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
|
|
|
|
|
|
|
|
|
|
### 4. 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 (e.g., integration tasks before foundational setup tasks without dependency note)
|
|
|
|
|
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
|
|
|
|
|
|
|
|
|
|
### 5. 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
|
|
|
|
|
|
|
|
|
|
### 6. Produce Compact Analysis Report
|
|
|
|
|
|
|
|
|
|
Output a Markdown report (no file writes) with the following structure:
|
|
|
|
|
|
|
|
|
|
## Specification Analysis Report
|
|
|
|
|
|
|
|
|
|
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
|
|
|
|
|----|----------|----------|-------------|---------|----------------|
|
|
|
|
|
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
|
|
|
|
|
|
|
|
|
|
(Add one row per finding; generate stable IDs prefixed by category initial.)
|
|
|
|
|
|
|
|
|
|
**Coverage Summary Table:**
|
|
|
|
|
|
|
|
|
|
| Requirement Key | Has Task? | Task IDs | Notes |
|
|
|
|
|
|-----------------|-----------|----------|-------|
|
|
|
|
|
|
|
|
|
|
**Constitution Alignment Issues:** (if any)
|
|
|
|
|
|
|
|
|
|
**Unmapped Tasks:** (if any)
|
|
|
|
|
|
|
|
|
|
**Metrics:**
|
|
|
|
|
|
|
|
|
|
- Total Requirements
|
|
|
|
|
- Total Tasks
|
|
|
|
|
- Coverage % (requirements with >=1 task)
|
|
|
|
|
- Ambiguity Count
|
|
|
|
|
- Duplication Count
|
|
|
|
|
- Critical Issues Count
|
|
|
|
|
|
|
|
|
|
### 7. Provide Next Actions
|
|
|
|
|
|
|
|
|
|
At end of report, output a concise Next Actions block:
|
|
|
|
|
|
|
|
|
|
- If CRITICAL issues exist: Recommend resolving before `/implement`
|
|
|
|
|
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
|
|
|
|
|
- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
|
|
|
|
|
|
|
|
|
|
### 8. 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 table to 50 rows; summarize overflow
|
|
|
|
|
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
|
|
|
|
|
|
|
|
|
|
### Analysis Guidelines
|
|
|
|
|
|
|
|
|
|
- **NEVER modify files** (this is read-only analysis)
|
|
|
|
|
- **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)
|
|
|
|
|
|
|
|
|
|
## Context
|
|
|
|
|
|
|
|
|
|
{ARGS}
|
|
|
|
|
|
den (work)