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:
2026-08-15 14:28:54 +02:00
co-authored by Claude Sonnet 5
parent 8f34371a9f
commit 051688e196
10 changed files with 1410 additions and 0 deletions
@@ -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:
- 25 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.