AGENT SKILL

spec-kitty.analyze

Cross-artifact consistency and quality analysis

License 许可
MIT
最近更新
2026-11-15
Stars
★ 2
Forks
0

01 前言 Front Matter

name
spec-kitty.analyze
description
Cross-artifact consistency and quality analysis
user-invocable
true

03 SKILL.md 正文

Startup Upgrade Check

Run this at most once per active agent session before the first Spec Kitty command workflow. If you already ran spec-kitty upgrade --agent-check --json in this session, reuse that result and skip this block. Do not run or announce an upgrade check again for later Spec Kitty commands in the same session. Otherwise, before continuing, run:

spec-kitty upgrade --agent-check --json

If JSON action is none, continue. If action is auto_upgrade, run upgrade_command before continuing. If it fails, tell the user and continue with the current Spec Kitty version. If action is guidance, show upgrade_note briefly, then continue. If action is prompt, ask the user with the host-native question UI when available:

Spec Kitty {latest_version} is available. You are on {installed_version}. Upgrade now?

Use these choices:

  1. Upgrade now (recommended) - record upgrade_now, run upgrade_command, then continue.
  2. Always keep me up to date - record always, run upgrade_command, then continue.
  3. Not now - record not_now, then continue.
  4. Never ask again - record never_ask, then continue.

Record the selected choice before continuing:

spec-kitty upgrade --agent-choice <upgrade_now|always|not_now|never_ask> --agent-latest <latest_version> --json

If no host-native question UI is available, present the same four choices in plain text and wait for the user. In non-interactive hosts, choose not_now and continue.

User Input

The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after /spec-kitty.<command> or $spec-kitty.<command>) is the User Input referenced elsewhere in these instructions.

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

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.

Operating Constraints

NON-REMEDIATING: Do not modify spec.md, plan.md, tasks.md, WP files, source code, or any remediation target. The only permitted file mutation is persisting this command's report to kitty-specs/<mission>/analysis-report.md via spec-kitty agent mission record-analysis. Offer an optional remediation plan only after the report is persisted (user must explicitly approve before any follow-up editing commands would be invoked manually).

Charter Authority: The project charter (.kittify/charter/charter.md) is non-negotiable within this analysis scope. Charter 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 charter update outside /analyze.

Issue-Matrix Approval Heads-Up (non-gating, #3469): if any artifact cites a GitHub issue number (#NNNN), a bare/unmarked reference will later require an issue-matrix row before its owning work package can be approved. A context-only citation (e.g. Follow-up:, see #, parent, epic) or a PR/commit reference (PR #NNNN, a /pull/NNNN URL) is non-gating and needs no row; if an issue genuinely owes the mission no work, it can later be recorded with the not-applicable verdict. This is informational only — it does not gate /spec-kitty.analyze.

Execution Steps

1. Initialize Analysis Context

Run spec-kitty agent mission check-prerequisites --json --include-tasks --mission <mission-slug> once from repo root and parse JSON for mission_dir, available_docs, target_branch, and base_branch. Derive absolute paths:

  • SPEC = mission_dir/spec.md
  • PLAN = mission_dir/plan.md
  • TASKS = mission_dir/tasks.md

Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).

2. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

From spec.md:

  • Overview/Context
  • Functional Requirements
  • Non-Functional Requirements
  • 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 charter:

  • Load .kittify/charter/charter.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)
  • Charter 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. Charter Alignment

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

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

The report MUST begin with a structured analysis-findings/v1 YAML frontmatter carrier, immediately followed by the human-readable Markdown body. The recorder computes the verdict and issue counts from this carrier only — report prose is presentation and is NEVER parsed for severity. Emit the carrier exactly in this shape:

---
schema: analysis-findings/v1
findings:
  - id: A1            # stable finding id (same id used in the body table)
    severity: high    # one of: low | medium | high | critical (closed vocabulary; no other values)
    category: coverage
    summary: "One-line description of the finding."
counts: {critical: 0, high: 1, medium: 0, low: 0, info: 0}   # MUST equal the findings[] tally per severity
verdict_hint: blocked   # OPTIONAL author hint; the recorder COMPUTES the verdict — if your hint disagrees, recording FAILS LOUDLY
---

Carrier rules (binding — a violation makes record-analysis fail on the write path):

  • findings[].severity MUST be one of low, medium, high, critical. Any other value fails schema validation.
  • counts per-severity values MUST equal the actual findings[] tally. info is a presentation-only bucket and never affects the verdict.
  • The verdict is derived from structure: any high or critical finding → blocked; otherwise → ready. Do not rely on prose wording.
  • If you include verdict_hint, it MUST match the computed verdict, or recording fails loudly.
  • A report with no findings emits findings: [] and counts: {critical: 0, high: 0, medium: 0, low: 0, info: 0} → verdict ready.

After the closing ---, draft the Markdown body 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

Charter 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. Persist Report Artifact

Save the Markdown report body to kitty-specs/<mission>/analysis-report.md by running the recorder with a temp report file outside the repository checkout:

spec-kitty agent mission record-analysis --mission <mission-slug> --input-file <path-to-temp-report.md> --json

If your host supports piping reliable multiline stdin, this equivalent form is acceptable:

spec-kitty agent mission record-analysis --mission <mission-slug> --input-file - --json

The report file you pass MUST start with the analysis-findings/v1 carrier from step 6. The recorder derives the verdict and counts from it; a malformed carrier (unknown severity, counts not matching the findings[] tally, or a disagreeing verdict_hint) makes the recorder fail loudly — fix the carrier and re-run.

Treat persistence failure as command failure. The command is not complete until the JSON response reports success and names analysis-report.md.

⚠️ Caution — write the report to a path OUTSIDE the repository checkout

The analysis-findings/v1 carrier (step 6) is the input format for record-analysis, not the persisted format. record-analysis wraps the carrier in the outer-wrapper format (artifact_type: spec-kitty.analysis-report) that the implement gate accepts.

Write the report body to a scratch file outside the repository checkout (a temp or scratch directory) and pass that path to record-analysis. Writing the report body into the checkout — including writing analysis-report.md directly — both leaves the file in carrier format (the implement gate then rejects it with carrier_format_not_wrapped) and dirties the worktree, so record-analysis refuses with DIRTY_WORKTREE. Recover by writing the body to a path outside the repository checkout and re-running record-analysis against that path:

TMP_REPORT="$(mktemp -t analysis-report.XXXXXX.md)"   # outside the repository checkout
# write the report body (starting with the analysis-findings/v1 carrier) to "$TMP_REPORT"
spec-kitty agent mission record-analysis --mission <mission-slug> --input-file "$TMP_REPORT" --json

7a. Report Currency (staleness rule)

The recorded analysis-report.md is current only while the planning inputs it was computed against are unchanged. Editing the spec, plan, tasks or the charter after the report is recorded makes it stale. A stale (or missing) report is refused downstream: spec-kitty next re-issues the analyze step, and spec-kitty implement refuses to claim a work package with analysis_report_required. Re-run /spec-kitty.analyze and record a fresh report whenever any of those inputs change.

8. 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 /spec-kitty.specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"

9. Offer Remediation

Ask the user: "Should all of these findings be addressed before moving on to implementation? I can suggest concrete remediation edits for the findings you want to resolve." (Do NOT apply edits 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 source/planning files other than the required analysis-report.md persistence step
  • NEVER hallucinate missing sections (if absent, report them accurately)
  • Prioritize charter 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

(User's invocation context is provided in the User Input section above.)

04 同仓库更多 Skills

spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-semi-auto

Use to take a tracker issue or a coherent issue-set through a governed delivery run that works autonomously but pauses to escalate the operator's decisions. Runs BOTH ways — in this session (local) or handed to a fresh cloud runner (cloud) — from one set of standing orders covering orientation, code grounding first, Mission-vs-Ops, the pause-and-escalate contract, brownfield discipline, and the canonical closeout to a draft PR the operator merges. Triggers: semi-auto, semi-auto dispatch, run this semi-automatically, deliver these issues semi-auto, hand this to a cloud runner, dispatch semi-auto.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-report-debrief

Use when a maintainer asks what happened or what is open ("what landed since Friday", "WTF happened with X", a milestone overview). Collects the facts from GitHub, writes a short branded debrief for named readers, and hands the PDF back without committing it. Triggers: what landed since, WTF happened, debrief the weekend, milestone overview, exec overview of open issues, write up what shipped.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-mission-from-issue

Use to take one or more GitHub issues through a full governed Mission (spec, plan, tasks, implementation, review) to a green pull request flipped to ready for review, which a maintainer then merges. Triggers: mission from issue, run a mission for this issue, drive issue to PR.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-land-pr

Use when a ready-for-review pull request needs a maintainer to get it ready to merge. Rebases it, fixes and reviews it, updates its description, changelog and docs, and hands it back without merging by hand. Triggers: land this PR, landing pass, land PR.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-issue-triage

Use to triage a batch of open GitHub issues on spec-kitty/spec-kitty (default, those opened in the last 7 days). Sets type, priority, domain, parent and milestone, and reports stale, duplicate or clustered issues for an operator decision. Triggers: triage issues, triage the tracker, triage new issues.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

spk-team-tracker

暂无简介

★ 2