feat: 10 new skills scouted from spec-kit and deepseek-harness
Sourced via Codex scan of github/spec-kit and deepseek-ai/deepseek-harness (scan reports in granja/_temp/codex-logs/), then authored by Codex against this repo's exact SKILL.md format/density, calibrated against bastille-jail-provisioning/writing-implementation-plans/tdd. Spot-checked two directly (write-feature-specification, harden-async-lifecycle-code) -- concrete, code-example-backed procedures, not generic advice. From spec-kit: write-feature-specification, clarify-feature-specification, audit-requirements-quality, analyze-spec-plan-task-consistency, converge-implementation-to-spec. From deepseek-harness: harden-async-lifecycle-code, test-real-entry-paths, snapshot-agent-behavior, maintain-decision-records, remove-reasoning-transcript-prose. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
---
|
||||
name: audit-requirements-quality
|
||||
description: Use when reviewing a specification, PRD, or requirements document for completeness, clarity, consistency, measurability, traceability, and scenario coverage without testing implementation behavior.
|
||||
---
|
||||
|
||||
# Audit Requirements Quality
|
||||
|
||||
Create “unit tests for English.” The checklist asks whether the requirements are written well enough to build and test. It never asks whether the product currently behaves correctly.
|
||||
|
||||
## The decisive distinction
|
||||
|
||||
Bad item — implementation test:
|
||||
|
||||
```markdown
|
||||
- [ ] Verify the page displays three featured cards.
|
||||
```
|
||||
|
||||
Good item — requirements-quality test:
|
||||
|
||||
```markdown
|
||||
- [ ] CHK001 Are the number, ordering, and selection rules for featured cards explicitly specified? [Completeness, Spec §FR-004]
|
||||
```
|
||||
|
||||
The bad item belongs in a test plan. The good item can fail while no code exists, because it evaluates the words.
|
||||
|
||||
## 1. Choose audit depth and focus
|
||||
|
||||
Read the authoritative requirements and any linked plan or principles needed to interpret them. State the requested focus, such as security, API, accessibility, migration, performance, or general readiness.
|
||||
|
||||
Use one of three depths:
|
||||
|
||||
- light: 10–15 highest-risk items;
|
||||
- standard: 20–30 items across all applicable dimensions;
|
||||
- deep: up to 40 items, including cross-section consistency and exception coverage.
|
||||
|
||||
Use a soft cap of 40. Merge near-duplicates and consolidate low-impact edge cases rather than producing checkbox noise.
|
||||
|
||||
## 2. Inventory the requirement surfaces
|
||||
|
||||
Collect stable requirement IDs, user journeys, acceptance criteria, success criteria, assumptions, dependencies, entities, and explicit exclusions. If IDs do not exist, cite headings and flag traceability as a gap.
|
||||
|
||||
Classify scenarios:
|
||||
|
||||
- primary;
|
||||
- alternate;
|
||||
- exception/error;
|
||||
- recovery/rollback;
|
||||
- non-functional;
|
||||
- boundary and empty state.
|
||||
|
||||
Do not infer that an implementation probably handles a missing scenario. Absence in the requirements is the finding.
|
||||
|
||||
## 3. Generate quality questions
|
||||
|
||||
Group items under applicable dimensions:
|
||||
|
||||
- Requirement Completeness
|
||||
- Requirement Clarity
|
||||
- Requirement Consistency
|
||||
- Acceptance Criteria Quality
|
||||
- Scenario Coverage
|
||||
- Edge Case Coverage
|
||||
- Non-Functional Requirements
|
||||
- Dependencies and Assumptions
|
||||
- Ambiguities and Conflicts
|
||||
- Traceability
|
||||
|
||||
Use these forms:
|
||||
|
||||
```markdown
|
||||
- [ ] CHK001 Are failure outcomes defined for every external dependency? [Completeness, Gap]
|
||||
- [ ] CHK002 Is “fast” quantified from the user’s perspective? [Clarity, Spec §NFR-002]
|
||||
- [ ] CHK003 Are retention obligations consistent between FR-008 and the privacy section? [Consistency, Spec §FR-008]
|
||||
- [ ] CHK004 Can the success threshold in SC-003 be measured objectively? [Measurability, Spec §SC-003]
|
||||
- [ ] CHK005 Are rollback requirements defined for interruption after partial migration? [Coverage, Gap]
|
||||
```
|
||||
|
||||
At least 80% of items must contain a direct section/ID reference or one of `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`, or `[Dependency]`.
|
||||
|
||||
## 4. Cover domain-relevant failure classes
|
||||
|
||||
Ask whether requirements exist and are precise for:
|
||||
|
||||
- actor permissions and ownership boundaries;
|
||||
- empty, loading, stale, duplicate, and partial data;
|
||||
- invalid input and dependency failures;
|
||||
- concurrency, conflict resolution, retries, and idempotency;
|
||||
- security failures, abuse limits, and sensitive-data handling;
|
||||
- accessibility and localization;
|
||||
- capacity, latency, degradation, and recovery targets;
|
||||
- deletion, retention, rollback, and irreversible operations;
|
||||
- compatibility, versioning, and migration.
|
||||
|
||||
Only include a class when it could plausibly affect the feature. A generic security checklist pasted onto a static copy edit is not a quality audit.
|
||||
|
||||
## 5. Apply the wording gate
|
||||
|
||||
Reject any item that:
|
||||
|
||||
- starts with “Verify,” “Test,” “Confirm,” or “Check” and then describes product behavior;
|
||||
- tells a user to click, navigate, render, execute, or load something;
|
||||
- says “works correctly,” “functions as expected,” or “displays properly”;
|
||||
- names code, framework internals, algorithms, or test procedures;
|
||||
- merely restates a requirement as a behavior assertion.
|
||||
|
||||
Require items to ask one of:
|
||||
|
||||
- Are requirements for X defined/documented?
|
||||
- Is vague term X quantified or clarified?
|
||||
- Are A and B consistent?
|
||||
- Can criterion X be objectively measured?
|
||||
- Are scenarios or edge cases X covered?
|
||||
- Does the document define missing aspect X?
|
||||
|
||||
## 6. Write a reviewer-owned artifact
|
||||
|
||||
Use globally increasing IDs and leave new items unchecked:
|
||||
|
||||
```markdown
|
||||
# <Focus> Requirements Checklist: <Feature>
|
||||
|
||||
**Purpose:** Evaluate the quality of written requirements for <focus>.
|
||||
**Source:** <document path or link>
|
||||
|
||||
**Marker semantics:** `[x]` means a reviewer found the requirements-quality criterion satisfied. It does not mean implementation is complete.
|
||||
|
||||
## Requirement Clarity
|
||||
|
||||
- [ ] CHK001 ...
|
||||
|
||||
## Notes
|
||||
|
||||
- Record the requirement edit or decision beside any resolved item.
|
||||
```
|
||||
|
||||
When appending to an existing checklist, continue from its maximum ID. Never delete, renumber, mark as passed, or overwrite reviewer-owned items during generation.
|
||||
|
||||
## 7. Self-audit the audit
|
||||
|
||||
Before handoff:
|
||||
|
||||
- every item tests prose quality, not runtime behavior;
|
||||
- categories reflect actual feature risk;
|
||||
- scenario classes are represented or intentionally excluded;
|
||||
- near-duplicates are merged;
|
||||
- at least 80% of items are traceable;
|
||||
- each item contains one answerable quality proposition;
|
||||
- new markers remain unchecked;
|
||||
- the list is within the selected depth cap.
|
||||
|
||||
Report item count, focus, depth, source documents, and the most material uncovered requirement areas. Do not claim the underlying requirements pass until a reviewer evaluates the checklist.
|
||||
Reference in New Issue
Block a user