goal-spec — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited goal-spec (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<!-- Copyright (c) 2026 JG Systems Consulting Ltd. MIT License — see LICENSE. -->
Convert a goal into a complete engineering specification. The goal-formatter answers "what does done look like?"; this skill answers "what exactly are we building, and how?" — by defining every section of the spec and asking the user gap-filling questions wherever the goal leaves a section under-determined.
This is the middle skill in a three-skill chain:
goal-formatter → goal-spec → spec-review
(goal + draft (THIS: full (autonomous
spec, optional) defined spec multi-discipline
via Q&A) hardening loop)Each skill is independently invocable. The handoff works because all three use the same 8-section engineering spec template (defined below — this skill owns it).
Trigger phrases:
Best for:
spec-reviewrefines* the draft rather than starting blank.
MAY proceed by inferring an implicit goal from the description.
This is the shared contract across goal-formatter (draft-spec mode), goal-spec, and spec-review. All three MUST use these exact section names so handoffs line up with no orphaned or renamed sections.
# Specification: <title>
## 1. Problem & Context
What problem this solves, why now, and the background a reader needs. Tie back to the
originating goal: one line stating the goal this spec satisfies.
## 2. Scope
- **In scope:** explicit list of what this spec covers.
- **Out of scope:** explicit list of what it deliberately excludes (prevents scope creep).
## 3. Requirements
- **Functional (FR1, FR2, …):** what the system MUST do, numbered for traceability.
- **Non-functional (NFR1, NFR2, …):** performance, security, reliability, usability,
maintainability targets — each measurable where possible.
## 4. Constraints
Hard limits the design must respect: tech stack, platforms, compatibility, regulatory,
budget, timeline, "must not change" baselines. Distinct from requirements — these bound
the solution space rather than describe behaviour.
## 5. Design Approach
The proposed solution shape: components, data flow, key interfaces, major decisions and
their rationale. Note alternatives considered and why rejected, where it matters.
## 6. Success Criteria
Observable, binary done/not-done conditions. Each criterion maps to a requirement and to a
verification step. (Inherits the goal's success criteria; refines them to spec granularity.)
## 7. Risks & Mitigations
What could go wrong (technical, integration, dependency, adoption) and the planned
mitigation or contingency for each.
## 8. Open Questions
Anything still undecided. Every item here is either (a) resolved via a clarifying question
to the user, or (b) explicitly flagged as deferred with an owner/trigger for resolution.A copy-pasteable version of this template lives at references/spec-template.md in this skill's directory.
spec is grounded in reality, not invented.
Fill every section from the goal + repo context. Where the goal supplies an answer, use it. Where it doesn't, mark the section with an explicit `[GAP: …]` placeholder describing what's missing — do NOT silently invent. Collect every [GAP: …] into the Open Questions section.
For each [GAP], decide: can I resolve it from the goal/repo, or must I ask the user?
Ask the user via `AskUserQuestion` when the gap is a genuine decision only they can make (scope boundary, priority, target numbers, tech choice, acceptable trade-off). Rules:
AskUserQuestion call.the question reads as "to satisfy your goal of X, which of these…?" not a generic survey.
sensible default.
assumption in the spec rather than asking.
Resolve yourself (no question) when the goal or repo already implies the answer, or a conventional default clearly applies — record it as a stated assumption in the relevant section.
with why it's deferred and what would resolve it).
the same system.
Run the Spec Self-Review Rubric (below) against the draft. Fix any FAIL (max 2 rounds), then present. This mirrors goal-formatter's step-3 gate — a spec that ships with hidden gaps fails downstream in spec-review or in implementation.
After presenting the spec, tell the user they can run `spec-review` to harden it through an autonomous multi-discipline review loop. Don't auto-invoke it — let the user choose.
The spec is written so any model or agent can implement from it without your context:
conversation history.
what can be built in parallel vs. what is strictly sequential.
INDEPENDENT (can be built concurrently by parallel subagents) vs. strictly sequential. The downstream executor uses this to parallelise; an undecomposed blob forces slow serial work.
Run against every drafted spec in step 5 before presenting. Each row PASS/FAIL. Any FAIL → revise (max 2 rounds), then present with explicit flags for anything still failing.
| # | Check | PASS looks like | FAIL looks like |
|---|---|---|---|
| 1 | All 8 sections present | Every template section has real content | A section missing or left as a heading |
| 2 | Requirements numbered & testable | Each FR/NFR is atomic, numbered, and verifiable | Vague blobs, unnumbered, untestable |
| 3 | Scope both ways | In-scope AND out-of-scope explicitly listed | Only in-scope, or open-ended |
| 4 | Constraints distinct from requirements | Constraints bound the solution; requirements describe behaviour | The two conflated or constraints absent |
| 5 | Design maps to requirements | Every FR is satisfied by something in Design Approach | Requirements with no design, or design for nothing |
| 6 | Success criteria measurable & mapped | Each criterion is binary, has a NUMERIC threshold (or an objective observation), AND names the verification method + sample size where physical | "Works well", adjectives, or a criterion with no stated test method |
| 7 | Grounded in repo reality | Paths, versions, counts verified, not guessed | Invented specifics |
| 8 | No silent gaps | Every gap is either resolved or listed in Open Questions | A [GAP] left buried in a section |
| 9 | Risks have mitigations | Each named risk has a mitigation/contingency | Risks listed with no response |
| 10 | Self-consistent | Sections 1, 3, 5, 6 describe the same system; a value (number/part/term) appears identically everywhere it is referenced | Sections contradict each other; the same fact stated two different ways |
| 11 | Every NFR/safety target is testable | Each performance, safety, or regulatory target is a number/range a test can pass/fail | A safety or perf target stated as an adjective, or with no acceptance test |
| 12 | No unstated assumptions | Any value the skill filled by default (not user-given) is explicitly labelled as an assumption | A specific value asserted as fact when it was actually a guess |
Revision discipline: fix the specific failing row; re-score only after editing. If two rounds can't clear a row, present the spec with that row flagged as a residual risk.
You say:
"Spec this goal" — and paste a goal-formatter goal about adding a rate limiter to the public API.
The skill:
what happens on breach (429 vs queue)? Marks each [GAP].
AskUserQuestion, grounded in the goal: *"To satisfy your goal of protecting thepublic API without harming legit users, which limiting strategy?"* → token-bucket (Recommended) / fixed-window / sliding-log, with trade-offs.
completes. If the user only has a rough idea, point them there first.
autonomous roundtable of engineering-discipline reviewers until it converges (no CRITICAL/MAJOR findings). Self-contained — no dependency on any other skill.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.