skills.rest
shftwst
shftwstOFFICIAL
Explore all skills by this author →
GitHub

faffter-dark-nlspec

Generates full nlspec-format specification documents for the faff-prep spec slot.

3|Updated Apr 16, 2026
Search Tags:#specification#spec generation#given-when-then#design decisions#nlspec#autonomous delivery#faff-prep
One-click install
npx skills add https://github.com/shftwst/faff --skill faffter-dark-nlspec-shftwst
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: faffter-dark-nlspec
Source: https://github.com/shftwst/faff/tree/main/plugin/skills/faffter-dark-nlspec
Command: npx skills add https://github.com/shftwst/faff --skill faffter-dark-nlspec-shftwst

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams running autonomous delivery pipelines need formal, buildable specifications that a coding agent can implement without extra context. This Skill produces the heavy, formal nlspec-format spec as the delegated spec slot in faff-prep, replacing the lighter default when a change demands rigor. ## Core Features & Use Cases - Nine-section nlspec structure: Produces WHY, OUT OF SCOPE, WHAT, HOW, Scenarios, Design Decision Rationale, Open Questions, DONE checklist, and optional appendices. - Deterministic contract markers: Emits canonical **Chosen:**, **Punt:**, **Assumes:** markers plus a machine-parseable faff-contract:spec-readiness JSON block so faff-prep validates decisions without re-reading prose. - Confidence self-rating with inherited quality bar: Ends with a confidence: high|medium|low line consumed by faff-prep's gate, capped by an inherited self-review that blocks high when blocker or major findings exist. - Use Case: Configure slots: spec: faffter-dark-nlspec in .faffrc so faff-prep generates a full formal spec — with Given-When-Then scenarios, holdout criteria, and a DONE checklist mirroring the body — for a complex architectural issue before an agent builds it. ## Quick Start Configure the spec slot in .faffrc to use faffter-dark-nlspec, then run faff-prep on an issue to generate a full nlspec-format specification.

Frequently Asked Questions about faffter-dark-nlspec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a formal spec with faff-prep?▼

Set the spec slot in .faffrc with `slots: spec: faffter-dark-nlspec`. When faff-prep runs, it passes the issue context, explore findings, and spec contract to this skill, which returns a full nlspec-format document that faff-prep validates and attaches to the issue.

What is the nlspec spec format?▼

The nlspec format is a nine-section specification structure: preamble, WHY, OUT OF SCOPE, WHAT (types and interfaces), HOW (behavior and pseudocode), Scenarios, Design Decision Rationale, Open Questions and Assumptions, and a DONE checklist. It is inspired by the NLSpec-Spec project but uses no code from it.

Can I invoke faffter-dark-nlspec directly from the user menu?▼

No. The skill is marked user-invocable: false and only runs as a delegated producer subagent inside faff-prep. You select it through the .faffrc slots configuration, not through the slash-command menu.

What are Chosen, Punt, and Assumes markers in a spec?▼

They are canonical decision markers required by the spec contract. `**Chosen:**` closes a decision, `**Punt:**` flags an open question needing a human, and `**Assumes:**` declares an external dependency. Faff-prep parses them deterministically from the contract block to make gate decisions.

How does the confidence rating affect spec promotion?▼

The skill ends each spec with a confidence line: high, medium, or low. In autonomous mode faff-prep promotes high-confidence specs, attaches medium ones flagged for review, and parks low ones. The rating is capped at medium if the inherited self-review finds a blocker or three major issues.

When should I use the full nlspec producer instead of the lite default?▼

Use it for changes above the complexity bar: spikes, novel integrations, architectural decisions, or designs resting on unvalidated assumptions. Mechanical CRUD work does not need the nine-section structure, failure-mode analysis, and holdout scenarios this producer emits.

Related Skills

Explore More Software Engineering Skills→
yashs33244yashs33244
1

to-issues

Convert plans into dependency-ordered issue tickets with acceptance criteria.

Community
Intermediate
DarkbluelrDarkbluelr
84

devbooks-coder

Automate coder implementation workflows with tasks.md adherence and gate-based verification.

Community
Advanced
DanSnowDanSnow
95

spectra-discuss

Facilitate structured technical discussions to reach consensus on architecture decisions.

Community
Advanced
legioncodeinclegioncodeinc
84

routine-architect

Audits and rewrites Littlebird routines against a nine-point alert-fatigue rubric.

Official
Advanced