AGENT SKILL

spec-quality-review

An optional pre-pass that surfaces spec defects for a human before freeze. Use when a spec was edited and spec freeze has not run, or when a bug suggests the spec contradicts itself.

License 许可
MIT
所属仓库
Eliyce/paqad-ai
最近更新
2026-11-13
Stars
★ 8
Forks
0

01 前言 Front Matter

name
spec-quality-review
metadata
{ "cacheable": "false", "model_tier": "reasoning", "paqad-meta": "skill.meta.yaml", "output_format": "markdown" }
description
An optional pre-pass that surfaces spec defects for a human before freeze. Use when a spec was edited and spec freeze has not run, or when a bug suggests the spec contradicts itself.

02 资源文件 7

03 SKILL.md 正文

What It Does

Surfaces likely spec defects (contradictions, formula inconsistencies, boundary gaps, goal conflicts, dangling references, and missing negative cases) as a human-readable list, so an author can fix them before freezing. It is an optional pre-pass, not the gate: paqad-ai spec freeze runs the authoritative, deterministic spec-quality review itself and blocks on a critical defect. This skill neither persists a report nor hands anything authoritative downstream.

Use This When

After a spec edit and before you run paqad-ai spec freeze, or when an implementation bug suggests the spec may be internally inconsistent, to catch defects early rather than at freeze time. Skipping it changes nothing about the freeze: the freeze runs its own review regardless.

Inputs

  • Read the target spec markdown file in full.
  • Read references/spec-defect-checklist.md before issuing findings.
  • Use agents/openai.yaml for the reasoning contract when the workflow executes through agent infrastructure.

Procedure

  1. Run scripts/scan-defects.sh <spec.md>: it skips Open Questions and TBD lines and emits candidate hits across the categories in assets/categories.txt (vague-quantifier, missing-actor, unbounded-modal, tbd-leak, dangling-ref, goal-collision, no-negative).
  2. Confirm each hit (or dismiss with a reason): the script flags candidates, you judge severity.
  3. Format a markdown summary per assets/output.template.md; validate it with scripts/lint-output.sh.
  4. Order findings by severity, then by source line.

Output Contract

  • Return a ## Findings section listing active defects with severity, category, location, and the specific clarification or rewrite needed.
  • Return a ## Resolved section only when a prior finding is now absent; omit it otherwise.
  • Persist nothing. This pre-pass writes no spec-review.json and no .paqad/compliance/** file: the freeze owns the authoritative record (its defect summary is folded into the bundle's specification.json).

Escalate / Stop Conditions

  • Escalate when the review cannot locate the spec file or the file is not markdown.
  • Stop short of rewriting the spec; report defects, do not auto-correct them.
  • This pre-pass never gates the build and never blocks freeze: the freeze's own deterministic review is the blocker. Report findings honestly; do not imply this pass is authoritative.

Resources

  • references/spec-defect-checklist.md
  • scripts/scan-defects.sh
  • scripts/lint-output.sh
  • assets/output.template.md
  • assets/categories.txt
  • agents/openai.yaml

04 同仓库更多 Skills

Eliyce
Eliyce/paqad-ai

sample-skill

Sample bundled skill fixture

★ 8
Eliyce
Eliyce/paqad-ai

processing-invoices

Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.

★ 8
Eliyce
Eliyce/paqad-ai

processing-invoices

Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.

★ 8
Eliyce
Eliyce/paqad-ai

understand-idea

Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.

★ 8
Eliyce
Eliyce/paqad-ai

size-work

Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.

★ 8
Eliyce
Eliyce/paqad-ai

refine-ticket

Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.

★ 8