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,129 @@
|
||||
---
|
||||
name: clarify-feature-specification
|
||||
description: Use when an existing feature specification is materially ambiguous or incomplete and its highest-impact decisions must be resolved before technical planning without expanding scope.
|
||||
---
|
||||
|
||||
# Clarify a Feature Specification
|
||||
|
||||
Clarification tightens an existing intent artifact. It does not create a new feature, choose an implementation, or turn optional ideas into scope.
|
||||
|
||||
## 1. Establish the authority and boundary
|
||||
|
||||
Read the entire current specification plus any project principles it claims to follow. If no specification exists, stop and request one; do not silently author a replacement.
|
||||
|
||||
Record the current in-scope and out-of-scope statements. Treat them as a fence. A proposed answer that adds a new actor, journey, business outcome, or integration is a scope change and requires explicit approval outside this workflow.
|
||||
|
||||
## 2. Build an ambiguity map
|
||||
|
||||
Mark each category `Clear`, `Partial`, or `Missing`:
|
||||
|
||||
- functional goals, boundaries, actors, and permissions;
|
||||
- entity identity, relationships, lifecycle, and scale assumptions;
|
||||
- primary, alternate, empty, error, and recovery flows;
|
||||
- performance, reliability, availability, and observability outcomes;
|
||||
- security, privacy, retention, and compliance obligations;
|
||||
- external dependencies, formats, compatibility, and failure modes;
|
||||
- conflicts, concurrency, throttling, and negative scenarios;
|
||||
- terminology and canonical names;
|
||||
- acceptance scenarios and measurable completion signals;
|
||||
- placeholders and vague adjectives.
|
||||
|
||||
Create a candidate question only if its answer would materially alter architecture, data modeling, task decomposition, test design, user-visible behavior, operational readiness, or compliance validation. Exclude stylistic preferences, already answered points, and choices properly owned by the technical plan.
|
||||
|
||||
## 3. Prioritize a small batch
|
||||
|
||||
Score each candidate using:
|
||||
|
||||
```text
|
||||
priority = impact × uncertainty × irreversibility
|
||||
```
|
||||
|
||||
Use High/Medium/Low values rather than fake numeric precision. Prefer one scope or security question over several polish questions. Cap a clarification session at five accepted questions; use three when that resolves the material uncertainty.
|
||||
|
||||
Questions must be answerable as either:
|
||||
|
||||
- 2–5 mutually exclusive choices with consequences; or
|
||||
- a short phrase explicitly limited to five words.
|
||||
|
||||
Ask one question at a time so later questions can be dropped or rewritten after each decision. Do not expose the whole internal queue.
|
||||
|
||||
## 4. Ask answerable questions
|
||||
|
||||
Use this form:
|
||||
|
||||
```markdown
|
||||
**Question:** Who may approve a refund above the ordinary limit?
|
||||
|
||||
This determines the permission boundary and the acceptance scenarios for high-value refunds.
|
||||
|
||||
**Recommended:** Option B — requiring a second approver limits unilateral high-value changes while preserving a defined path.
|
||||
|
||||
| Option | Answer | Consequence |
|
||||
|--------|--------|-------------|
|
||||
| A | Any refund operator | Simplest flow; broadest authority |
|
||||
| B | Two refund operators | Adds dual control and an intermediate state |
|
||||
| C | Finance administrator only | Narrowest authority; may delay completion |
|
||||
|
||||
Reply with A, B, C, “recommended,” or a short alternative.
|
||||
```
|
||||
|
||||
The question must be a complete interrogative, not a topic label such as “Refund permissions.” Explain why it matters before listing options. Recommend only when the existing context supports a best default; otherwise state the trade-off neutrally.
|
||||
|
||||
Validate the reply. If it does not map to an option or is too vague, ask a disambiguation without counting a new question. Accept “recommended” only when a recommendation was shown.
|
||||
|
||||
Stop when critical ambiguity is resolved, the user says to stop, or five answers have been accepted. Report high-impact deferred questions rather than exceeding the cap.
|
||||
|
||||
## 5. Integrate each answer immediately
|
||||
|
||||
After every accepted answer:
|
||||
|
||||
1. add one audit bullet under `## Clarifications` and a dated session heading;
|
||||
2. edit the authoritative section where the decision belongs;
|
||||
3. remove or replace the now-invalid ambiguous wording;
|
||||
4. save the file before asking the next question.
|
||||
|
||||
```markdown
|
||||
## Clarifications
|
||||
|
||||
### Session 2026-08-15
|
||||
|
||||
- Q: Who may approve a refund above the ordinary limit? → A: Two refund operators.
|
||||
```
|
||||
|
||||
Route the decision by kind:
|
||||
|
||||
- functional answer → functional requirement;
|
||||
- actor or sequence answer → journey and acceptance scenarios;
|
||||
- entity answer → entity identity, relationship, or lifecycle;
|
||||
- quality answer → measurable success criterion;
|
||||
- failure answer → edge case or exception scenario;
|
||||
- terminology answer → normalize the canonical term throughout.
|
||||
|
||||
Write the smallest testable change. Do not append a clarification while leaving contradictory alternatives elsewhere. If the answer changes settled scope, pause and label it a scope amendment rather than integrating it as routine clarification.
|
||||
|
||||
## 6. Validate after each edit
|
||||
|
||||
Check:
|
||||
|
||||
- exactly one clarification bullet exists per accepted answer;
|
||||
- the answer appears in the normative section, not only the audit log;
|
||||
- the triggering placeholder or vague phrase is gone;
|
||||
- no earlier statement asserts a rejected alternative;
|
||||
- IDs, heading hierarchy, and unrelated ordering are preserved;
|
||||
- canonical terminology is consistent;
|
||||
- no new actor, journey, or requirement slipped in without being implied by the answer.
|
||||
|
||||
If a requirements-quality checklist exists, re-evaluate it against the edited spec. Toggle only checklist state that the clarified text actually changes; preserve all other wording and formatting.
|
||||
|
||||
## 7. Report the result
|
||||
|
||||
Report:
|
||||
|
||||
- number of questions accepted;
|
||||
- specification path;
|
||||
- sections changed;
|
||||
- categories resolved, clear, deferred, and still outstanding;
|
||||
- any checklist items that changed state;
|
||||
- whether planning can safely begin.
|
||||
|
||||
If no candidate meets the materiality threshold, say that no critical ambiguity warrants formal clarification. Do not invent questions to fill a quota.
|
||||
Reference in New Issue
Block a user