OneLinersCommand workbench
AI
Back to skills
SKILL.md

Requirements clarification skill

An evidence-first workflow to turn an ambiguous request into testable outcomes, constraints, and explicit non-goals.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/requirements-clarifier/SKILL.md
Claude Code.claude/skills/requirements-clarifier/SKILL.md
VS Code.github/skills/requirements-clarifier/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: requirements-clarifier
description: Turns an ambiguous request into an evidence-labeled decision log and concrete acceptance cases. Use before implementation when scope, boundaries or success are unclear; never promote a proposal to an approved requirement.
license: CC-BY-4.0
compatibility: Complete fictional CSV brief and decision exercise use Node.js 22.13+ only if run. No repository, tracker, private data or network required. Actual product decisions must come from the authorized stakeholder/evidence source.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Requirements clarification skill

## Separate the user's goal from an implementation guess
Identify actor, current pain, desired outcome, affected users and existing constraints. Ask the few questions whose answers change scope, risk or acceptance most. Record evidence as confirmed, proposed or unknown; a confident model-generated sentence is not a stakeholder decision. Keep explicit non-goals so clarification does not expand into a platform rebuild.

## Complete original CSV-export brief
The included brief and ledger are the entire fictional input. They intentionally do not contain all answers. Each acceptance case names its prerequisite decisions rather than hiding a default in implementation.

```json
{
  "context": "Fictional tenant workspace; no OneLiners request or customer record.",
  "brief": "Let workspace readers download CSV quickly. Keep existing tenant access rules. The date range should make sense; do not build scheduling in this change.",
  "decisions": [
    {
      "id": "D1",
      "topic": "actor and access",
      "state": "confirmed",
      "value": "Existing authenticated reader permission and tenant boundary remain unchanged",
      "source": "supplied brief sentences 1–2"
    },
    {
      "id": "D2",
      "topic": "export scope",
      "state": "unknown",
      "value": null,
      "question": "Current visible filters, selected rows or all authorized rows?"
    },
    {
      "id": "D3",
      "topic": "date semantics",
      "state": "unknown",
      "value": null,
      "question": "Which timestamp/timezone and inclusive or half-open interval?"
    },
    {
      "id": "D4",
      "topic": "size and completion budget",
      "state": "proposed",
      "value": "Draft only: at most 1000 rows with an explicit too-large result; target response budget to be agreed",
      "question": "What real sizes, environment and success percentile/budget matter?"
    },
    {
      "id": "D5",
      "topic": "CSV consumer and safety",
      "state": "unknown",
      "value": null,
      "question": "UTF-8/BOM/delimiter, spreadsheet consumer and formula-like cell policy?"
    },
    {
      "id": "D6",
      "topic": "non-goal",
      "state": "confirmed",
      "value": "No scheduled exports in this change",
      "source": "supplied brief final clause"
    }
  ],
  "acceptance": [
    {
      "id": "A1",
      "requires": [
        "D1"
      ],
      "check": "An authorized reader sees only that reader's permitted tenant rows; another tenant and an unauthorized user cannot export them."
    },
    {
      "id": "A2",
      "requires": [
        "D2"
      ],
      "check": "A known filtered/selected fixture exports exactly the agreed row IDs, in the agreed order, with no silently omitted rows."
    },
    {
      "id": "A3",
      "requires": [
        "D3"
      ],
      "check": "Rows exactly at each agreed time boundary, timezone conversion and empty range have explicit expected inclusion/results."
    },
    {
      "id": "A4",
      "requires": [
        "D4"
      ],
      "check": "At/over the agreed size and time limits, the caller receives the agreed complete success or explicit rejection, never a silent truncated success."
    },
    {
      "id": "A5",
      "requires": [
        "D5"
      ],
      "check": "Comma, quote, newline, non-ASCII and formula-like cells follow the confirmed format/consumer policy without unauthorized data changes."
    }
  ]
}
```

## Worked clarification and acceptance readiness
Confirmed from this fictional brief: existing readers/tenant authorization stay in force (D1), and scheduling is outside this change (D6). CSV is the requested delivery, but that does not decide row scope, timestamp/timezone, limits, consumer encoding or spreadsheet safety. "Quickly" is not a measured percentile or a response-time budget. The 1000-row idea in D4 is explicitly a proposal, not an owner-approved requirement or a performance result.

Ask first which rows the user needs and for which downstream task (D2); which timestamp/timezone/boundaries define the date range (D3); and the real consumer/format plus size/time constraints (D4/D5). Show the consequences: all rows can require a different delivery model than visible filtered rows; a local calendar day is not necessarily a UTC day; silently truncating at a cap may be worse than an explicit too-large result. Do not turn this into a request for unnecessary customer records.

Acceptance A1 can be specified from the preserved access rule. A2–A5 still depend on unresolved D2–D5; the local inventory check correctly reports four blocked criteria and ready=false. A source-reference label only documents where a decision should be verified; changing it cannot authorize a new feature. Do not invent product-owner responses, silently promote proposals or claim the acceptance tests ran.

Return a narrow contract: actor/outcome, confirmed constraints and non-goals, decision log with owners, these concrete boundary/denial/format cases, unresolved choices and the next interview/research step. After real decisions, replace placeholders with exact expected rows/time boundaries/limits and link each acceptance case to that source before implementation. Preserve a decision's history when it changes. This exercise validates a complete supplied decision inventory in memory; it exports no CSV, changes no product and sends no stakeholder message.

## Optional local decision-inventory check
Save this complete block as requirements-fixture.mjs and run node requirements-fixture.mjs with Node.js 22.13+. It checks references/evidence states, not the truth of a source or the feature implementation. All data are embedded; it reads/writes no external data and contacts nobody.

```js
import assert from "node:assert/strict";
const requirementCase = {
  "context": "Fictional tenant workspace; no OneLiners request or customer record.",
  "brief": "Let workspace readers download CSV quickly. Keep existing tenant access rules. The date range should make sense; do not build scheduling in this change.",
  "decisions": [
    {
      "id": "D1",
      "topic": "actor and access",
      "state": "confirmed",
      "value": "Existing authenticated reader permission and tenant boundary remain unchanged",
      "source": "supplied brief sentences 1–2"
    },
    {
      "id": "D2",
      "topic": "export scope",
      "state": "unknown",
      "value": null,
      "question": "Current visible filters, selected rows or all authorized rows?"
    },
    {
      "id": "D3",
      "topic": "date semantics",
      "state": "unknown",
      "value": null,
      "question": "Which timestamp/timezone and inclusive or half-open interval?"
    },
    {
      "id": "D4",
      "topic": "size and completion budget",
      "state": "proposed",
      "value": "Draft only: at most 1000 rows with an explicit too-large result; target response budget to be agreed",
      "question": "What real sizes, environment and success percentile/budget matter?"
    },
    {
      "id": "D5",
      "topic": "CSV consumer and safety",
      "state": "unknown",
      "value": null,
      "question": "UTF-8/BOM/delimiter, spreadsheet consumer and formula-like cell policy?"
    },
    {
      "id": "D6",
      "topic": "non-goal",
      "state": "confirmed",
      "value": "No scheduled exports in this change",
      "source": "supplied brief final clause"
    }
  ],
  "acceptance": [
    {
      "id": "A1",
      "requires": [
        "D1"
      ],
      "check": "An authorized reader sees only that reader's permitted tenant rows; another tenant and an unauthorized user cannot export them."
    },
    {
      "id": "A2",
      "requires": [
        "D2"
      ],
      "check": "A known filtered/selected fixture exports exactly the agreed row IDs, in the agreed order, with no silently omitted rows."
    },
    {
      "id": "A3",
      "requires": [
        "D3"
      ],
      "check": "Rows exactly at each agreed time boundary, timezone conversion and empty range have explicit expected inclusion/results."
    },
    {
      "id": "A4",
      "requires": [
        "D4"
      ],
      "check": "At/over the agreed size and time limits, the caller receives the agreed complete success or explicit rejection, never a silent truncated success."
    },
    {
      "id": "A5",
      "requires": [
        "D5"
      ],
      "check": "Comma, quote, newline, non-ASCII and formula-like cells follow the confirmed format/consumer policy without unauthorized data changes."
    }
  ]
};
function checkRequirementReadiness(contract) {
  assert.ok(Array.isArray(contract.decisions) && contract.decisions.length > 0 && Array.isArray(contract.acceptance) && contract.acceptance.length > 0, "nonempty decision and acceptance inventory required");
  const decisions = new Map();
  for (const decision of contract.decisions) {
    assert.ok(typeof decision.id === "string" && !decisions.has(decision.id), "unique decision ID required");
    assert.ok(["confirmed", "proposed", "unknown"].includes(decision.state), "explicit evidence state required");
    if (decision.state === "confirmed") assert.ok(typeof decision.source === "string" && decision.source.length > 0 && decision.value, "confirmed decision needs a value and source reference");
    decisions.set(decision.id, decision);
  }
  const blockedAcceptance = [], criterionIds = new Set();
  for (const criterion of contract.acceptance) {
    assert.ok(typeof criterion.id === "string" && !criterionIds.has(criterion.id), "unique acceptance ID required"); criterionIds.add(criterion.id);
    assert.ok(criterion.check && Array.isArray(criterion.requires) && criterion.requires.length > 0, "testable criterion and decision references required");
    for (const id of criterion.requires) assert.ok(decisions.has(id), "acceptance references missing decision: " + id);
    const unresolved = criterion.requires.filter((id) => decisions.get(id).state !== "confirmed");
    if (unresolved.length) blockedAcceptance.push({ id: criterion.id, unresolved });
  }
  return { confirmed: [...decisions.values()].filter((d) => d.state === "confirmed").map((d) => d.id), proposed: [...decisions.values()].filter((d) => d.state === "proposed").map((d) => d.id), unanswered: [...decisions.values()].filter((d) => d.state === "unknown").map((d) => d.id), blockedAcceptance, readyForAcceptanceDefinition: blockedAcceptance.length === 0, limitation: "Inventory consistency only; source labels are not authentication, owner approval, implemented tests or a released feature." };
}
const result = checkRequirementReadiness(requirementCase);
assert.deepEqual(result.confirmed, ["D1", "D6"]);
assert.deepEqual(result.proposed, ["D4"]);
assert.deepEqual(result.unanswered, ["D2", "D3", "D5"]);
assert.equal(result.readyForAcceptanceDefinition, false);
console.log(JSON.stringify(result, null, 2));
```

## Handoff and stop condition
[GOV.UK user-story guidance](https://www.gov.uk/service-manual/agile-delivery/writing-user-stories) is a useful reference for connecting a user's goal with observable acceptance; the case/decisions here are original, not a requirement to use one story syntax. Return the decision contract and unanswered questions in the team's existing tracker. Do not claim an estimate, latency target, legal policy or export format is approved without evidence. Pause the affected implementation when unresolved authority, data scope or acceptance would materially change the result; continue safe agreed discovery rather than choosing hidden defaults.

Real example

Input

Review the complete fictional CSV brief, D1–D6 decision ledger and A1–A5 acceptance dependencies in SKILL.md. Separate confirmed/proposed/unknown, ask the scope-changing questions and show why four acceptance criteria remain blocked. Do not invent stakeholder answers or implement an export.

Expected result

Confirmed from this fictional brief: existing readers/tenant authorization stay in force (D1), and scheduling is outside this change (D6). CSV is the requested delivery, but that does not decide row scope, timestamp/timezone, limits, consumer encoding or spreadsheet safety. "Quickly" is not a measured percentile or a response-time budget. The 1000-row idea in D4 is explicitly a proposal, not an owner-approved requirement or a performance result.

Ask first which rows the user needs and for which downstream task (D2); which timestamp/timezone/boundaries define the date range (D3); and the real consumer/format plus size/time constraints (D4/D5). Show the consequences: all rows can require a different delivery model than visible filtered rows; a local calendar day is not necessarily a UTC day; silently truncating at a cap may be worse than an explicit too-large result. Do not turn this into a request for unnecessary customer records.

Acceptance A1 can be specified from the preserved access rule. A2–A5 still depend on unresolved D2–D5; the local inventory check correctly reports four blocked criteria and ready=false. A source-reference label only documents where a decision should be verified; changing it cannot authorize a new feature. Do not invent product-owner responses, silently promote proposals or claim the acceptance tests ran.

Return a narrow contract: actor/outcome, confirmed constraints and non-goals, decision log with owners, these concrete boundary/denial/format cases, unresolved choices and the next interview/research step. After real decisions, replace placeholders with exact expected rows/time boundaries/limits and link each acceptance case to that source before implementation. Preserve a decision's history when it changes. This exercise validates a complete supplied decision inventory in memory; it exports no CSV, changes no product and sends no stakeholder message.

Source evidence

Agent Skills specificationofficialGitHub issue formsofficialGOV.UK Service Manual — user goals and acceptanceofficial