agent-skills/skills/analyze-spec-plan-task-consistency/SKILL.md

name, description

name	description
analyze-spec-plan-task-consistency	Use when a feature specification, technical plan, task list, and project principles exist and need a read-only semantic audit for conflicts, ambiguity, duplication, underspecification, traceability, and coverage gaps before implementation.

Analyze Spec, Plan, and Task Consistency

Perform a read-only audit. Do not edit the artifacts, generate replacement tasks, or resolve policy conflicts silently. The output is a traceable findings report that lets the owner decide what to change.

1. Require a complete artifact set

Locate and read:

• feature specification;
• technical plan;
• implementation task list;
• project principles, constitution, ADRs, or mandatory policy, when present.

Stop if spec, plan, or tasks are missing. Partial analysis produces misleading coverage numbers. Treat an unfilled policy template as absent and say so.

2. Build normalized inventories

Extract only normative or buildable content.

From the spec:

• functional requirements and stable IDs;
• user journeys and acceptance scenarios;
• edge cases;
• buildable success criteria, excluding post-launch business KPIs;
• assumptions and exclusions.

From the plan:

• architecture and stack decisions;
• data model and contracts;
• named components and file touch-points;
• technical constraints, migration, and verification strategy.

From tasks:

• task IDs, phase, dependencies, and parallel markers;
• action, file path, and claimed requirement/story association.

From principles:

• every MUST, MUST NOT, and materially relevant SHOULD.

Normalize equivalent phrases to one concept key such as account-recovery or retention-window, while preserving original IDs for citations.

3. Run six detection passes

Duplication

Find requirements or tasks that express the same obligation with different IDs. Distinguish harmless local restatement from two authorities that can drift. Flag duplicates when ownership, criteria, or wording differ materially.

Ambiguity

Find vague adjectives, unresolved placeholders, undefined actors, unclear pronouns, missing quantities, or terms used with multiple meanings. Quote the shortest relevant phrase and state what decision cannot be derived.

Underspecification

Find journeys without acceptance scenarios, requirements without observable outcomes, plan choices without failure/compatibility treatment, and tasks without files or verifiable completion conditions.

Conflict

Compare:

• requirement against requirement;
• requirement against plan decision;
• task against requirement or plan;
• every artifact against mandatory principles.

A stricter plan is not automatically a conflict; it is a conflict when it changes stated behavior, excludes required scope, or violates an authority.

Coverage

Build both directions:

requirement/criterion → plan decision(s) → task(s)
task → originating requirement, plan decision, or principle

Flag requirements with no task, tasks with no source, acceptance scenarios with no implementation path, and principle obligations with no enforcement or verification work.

Ordering and feasibility

Find tasks that consume artifacts before they are created, claim unsafe parallelism on the same file/shared state, omit migrations or wiring, or schedule integration proof before a runnable composition exists.

4. Assign severity

Use:

• CRITICAL: violates a mandatory principle, creates a security/privacy breach, or makes P1 behavior impossible.
• HIGH: uncovered core requirement, direct spec/plan conflict, or task set cannot deliver an acceptance scenario.
• MEDIUM: meaningful ambiguity, secondary coverage gap, unsupported task, or ordering risk.
• LOW: localized duplication, terminology drift, or polish-level traceability weakness.

Do not inflate severity because an item is easy to notice. When uncertain between two levels, choose the lower and state the uncertainty.

5. Report findings with evidence

Use stable IDs such as A001 and order by severity, then by artifact order.

| ID | Category | Severity | Locations | Finding | Recommendation |
|----|----------|----------|-----------|---------|----------------|
| A001 | Coverage | HIGH | FR-008; tasks.md | No task implements or verifies revocation of active challenges. | Add a vertical task covering state change and acceptance proof. |

Every finding must cite at least two locations for a conflict/duplication, or one location plus an explicit missing mapping for a gap. Recommendations name the artifact that owns the correction; they do not draft the correction.

6. Provide coverage metrics

Report:

Requirements mapped to ≥1 task: 18/20 (90%)
Acceptance scenarios mapped: 7/9 (78%)
Tasks with an authoritative source: 24/26 (92%)
Mandatory principles represented: 4/5 (80%)

Counts are navigation aids, not proof of quality. One task mentioning an ID does not count as coverage unless its action could satisfy the obligation. One task may cover several requirements, and one requirement may need several tasks.

7. Self-check and handoff

• no artifact was modified;
• every finding is evidence-backed and non-duplicative;
• all mandatory principles were inspected;
• both requirement-to-task and task-to-intent mappings were checked;
• severity follows impact rather than wording;
• recommendations preserve artifact ownership;
• a zero-finding report includes inventory and coverage counts.

End with the top three remediation priorities and state whether implementation should pause. Any CRITICAL finding or unresolved HIGH conflict means pause; ordinary MEDIUM gaps may be corrected before or during planning at the owner’s discretion.