kiss-verify-tasks

name	kiss-verify-tasks
description	Performs a non-destructive cross-artefact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. Use when validating tasks.md after running kiss-taskify, checking that tasks align with the spec and plan, or before starting implementation.
compatibility	Requires kiss project structure with .kiss/ directory
metadata	{"author":"github-kiss","source":"agent-skills/kiss-verify-tasks/kiss-verify-tasks.md"}

User Input

$ARGUMENTS

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

Audience and tone (interactive mode)

When KISS_AGENT_MODE=interactive (the default), assume the user has limited technical background and limited domain knowledge — they may know basics but lack deep expertise in cross-artefact consistency analysis. Run this skill as a guided questionnaire:

• One question at a time. No walls of questions.
• Yes / no first. Phrase so yes, no, not sure, or skip is a valid answer.
• Translate jargon, don't strip it. Use the term but pair it with a plain-English gloss: "Cross-artefact consistency (do spec.md, plan.md, and tasks.md still tell the same story, or did one drift?)".
• Choices, not blank fields. When yes/no isn't enough, offer 2-4 lettered options (A/B/C/D) with one-line plain-language descriptions of the trade-off. Always include "Not sure — pick a sensible default".
• Always recommend. State the option you would pick and why in one sentence so the user can reply "yes" / "ok" to accept.
• Show, don't ask. Pre-show the inconsistencies you found and ask "do these matter? (yes / no per finding)" rather than asking the user to read three files themselves.
• not sure / skip triggers a sensible default, marked "(default applied — confirm later)" in the analysis report, and a debt entry.

When KISS_AGENT_MODE=auto (or --auto), skip the questionnaire entirely: surface the inconsistency report and log decisions to the parent agent's decision log. Never auto-modify spec.md / plan.md / tasks.md to "fix" an inconsistency — that requires the user.

Pre-Execution Checks

Check for extension hooks (before analysis):

• Check if .kiss/extensions.yml exists in the project root.

• If it exists, read it and look for entries under the hooks.before_verify-tasks key

• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.

• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:

  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation

• For each executable hook, output the following based on its optional flag:

  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Goal.
    

• If no hooks are registered or .kiss/extensions.yml does not exist, skip silently

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 /kiss.taskify has successfully produced a complete tasks.md.

Operating Constraints

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).

Standards Authority: The project standards ({context.paths.docs}/standards.md) is non-negotiable within this analysis scope. Standards 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 standards update outside /kiss.verify-tasks.

Execution Steps

1. Initialize Analysis Context

Run scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks 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). For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

From spec.md:

• Overview/Context
• Functional Requirements
• Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
• User Stories
• Edge Cases (if present)

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 standards:

• Load {context.paths.docs}/standards.md for principle validation

3. Build Semantic Models

Create internal representations (do not include raw artifacts in output):

• Requirements inventory: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → user-can-upload-file). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
• 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)
• Standards 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. Standards Alignment

• Any requirement or plan element conflicting with a MUST principle
• Missing mandated sections or quality gates from standards

E. Coverage Gaps

• Requirements with zero associated tasks
• Tasks with no mapped requirement/story
• Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks

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 standards 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

Standards 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 /kiss.implement
• If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
• Provide explicit command suggestions: e.g., "Run /kiss.specify with refinement", "Run /kiss.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.)

9. Check for extension hooks

After reporting, check if .kiss/extensions.yml exists in the project root.

• If it exists, read it and look for entries under the hooks.after_verify-tasks key

• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.

• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:

  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation

• For each executable hook, output the following based on its optional flag:

  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

• If no hooks are registered or .kiss/extensions.yml does not exist, skip silently

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 standards 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

$ARGUMENTS

Inputs

• Feature Specification ({context.current.spec}): current.spec.

  • If set: Read the specification.
  • If null: Search {context.paths.specs} for the most recent spec.md.
  • If not provided: Proceed; analysis may be incomplete without spec.

• Implementation Plan ({context.current.plan}): current.plan.

  • If set: Read the plan.
  • If null: Search {context.paths.plans} for the most recent plan.md.
  • If not provided: Proceed; analysis may be incomplete without plan.

• Tasks List ({context.current.tasks}): current.tasks.

  • If set: Read the tasks list.
  • If null: Search {context.paths.tasks} for the most recent tasks.md.
  • If not provided: Proceed; analysis may be incomplete without tasks.

Outputs

• Analysis Report (stdout): stdout.
  • Behavior: Output analysis findings to the user. Optionally write to {context.paths.plans}/{context.current.feature}/analysis.md if requested.
  • Overwrite guarded by {context.preferences.confirm_before_write}.

Context Update

After this skill completes successfully, update .kiss/context.yml:

• Do not update context.yml (analysis is non-destructive reporting only)