requirements-clarification

name

requirements-clarification

description

Attach this capability as the default requirement-normalization step for ordinary implementation-shaped requests that are not yet execution-ready. It treats the user's instruction as a stated requirement, decomposes atomic requirements, records attribute status, field grounding, inferred candidates, rejected assumptions, and remaining source or capability obligations. Do not use it for purely factual questions, pure local investigation, or pure public research with no implementation intent. Expected result: a written requirements artifact plus a next capability set.

Requirements Clarification

Purpose

This capability turns a raw implementation request into an execution-ready requirements artifact.

Its starting assumption is that the user's initial instruction is a stated requirement: useful, but not yet analyzed, verified, or validated enough for direct execution.

The goal is to reduce task-framing ambiguity for smaller models by replacing "does this feel specific enough?" with a fixed requirements record, explicit attribute status, and a clear boundary between binding requirements and non-binding inferences.

When to use

Attach this capability as the default first step when the request is an ordinary implementation-shaped task and one or more of these are true:

• the request names a change but not the full execution-ready requirement set
• the request implies invariants, tests, docs, or verification work that are not yet explicit
• the request may hide multiple atomic requirements inside one instruction
• the request needs a normalized artifact before planning or implementation
• the request looks specific but still relies on unstated assumptions about scope, constraints, or acceptance criteria

When not to use

Do not attach this capability when:

• the request is a purely factual question with no implementation intent
• the request is clearly pure public research
• the request is clearly pure repository-local investigation
• the request is clearly behavior-preserving refactoring and already execution-ready
• the request already has a written requirements artifact or task file that is good enough for the next downstream capability set

Expected inputs

• the raw user request
• any explicit user constraints, preferences, or prior decisions
• relevant repository context discoverable from local files
• public sources when externally grounded facts are needed for the requirement record

Expected outputs

• a structured requirements document written to .opencode/work/req-<slug>.md
• atomic requirement records with explicit attribute status
• targeted user questions only for remaining unknown attributes
• a next capability set or handoff recommendation

Core rules

1. Start from stated requirements

Do not treat the user's first wording as automatically execution-ready.

Instead, convert it into one or more atomic requirements.

2. Split into atomic requirements

Each atomic requirement should express one of:

• a capability
• a constraint
• a quality expectation

Do not leave several independently verifiable changes fused into one record.

3. Normalize every atomic requirement

For each atomic requirement, fill a fixed record.

Use an EARS-style statement when practical, but prefer a precise fixed structure over free-form prose.

Each record must contain at least:

• Type
• Normalized statement
• Source
• Target
• Desired change
• Invariants
• Constraints
• Acceptance criteria
• Verification method
• Affected tests
• Affected docs

4. Track attribute status explicitly

For every required attribute, record exactly one of:

• user_provided
• repo_derivable
• public_fact
• unknown

Use these meanings:

• user_provided: the user already gave the value clearly enough
• repo_derivable: the value should be determined from repository context
• public_fact: the value depends on externally verifiable public information
• unknown: the value still requires a real user decision or remains unresolved after proportionate discovery

Do not collapse these statuses into a vague statement such as "unclear."

Attribute status is not evidence by itself. Treat repo_derivable and public_fact as source classes that must be investigated before the value can become binding. Do not write a plausible value into a binding requirement merely because it seems likely to be derivable from the repository or from public sources.

4a. Separate requirement authority from candidate inference

Each requirement-level claim must be one of:

• binding: supported by user-stated facts, repository-observed facts, public-source facts, project rules, or valid deductions from those inputs
• candidate: plausible but still dependent on an auxiliary assumption, incomplete source coverage, or a user decision
• unknown: required but not yet resolved
• rejected: a tempting assumption that must not guide downstream work

Only binding claims may define desired change, invariants, constraints, acceptance criteria, verification methods, affected tests, affected docs, or implementation premises. Candidate requirements may be recorded to preserve the idea, but they are non-binding until confirmed by evidence or accepted by the user.

5. Discover before asking

Before asking the user, inspect the repository and attach public research when needed.

Ask only about attributes that remain unknown after proportionate discovery.

6. Map unresolved attributes to capability obligations, not intuition

Use this mapping:

• unresolved required repo_derivable attributes -> include investigation
• unresolved required public_fact attributes -> include public-research
• unresolved required unknown attributes -> stay in this skill and ask targeted questions, or attach grill-me only if the remaining decisions are interdependent
• no unresolved required attributes -> recommend the smallest sufficient next capability set, such as task-planning, implementation, refactoring, code-review, investigation, public-research, or epistemic-audit as appropriate

Do not hand off to implementation while a required attribute is still unknown.

Do not hand off to implementation while any binding field still depends on a candidate claim.

7. Make change obligations explicit

The requirement record must surface change obligations that small models often miss.

At minimum, make explicit:

• what existing behavior must remain true
• what new behavior must be verified
• which tests are affected
• which docs are affected

If you determine that no test or doc update is needed, say so explicitly instead of leaving the field blank.

8. Write the artifact

Write the requirements document to .opencode/work/req-<slug>.md unless the user asked for another location.

If the directory does not exist, create it.

Requirements document template

Use this structure:

# Requirements: <title>

## Objective

<One sentence stating what must be achieved.>

## Scope

- In scope:
  - <item>
- Out of scope:
  - <item>

## Binding metadata

- task_slug: <slug>
- source request summary: <brief summary>
- target repository or path: <repo or path>
- base_commit: <commit hash or `unknown`>
- status: draft | active | superseded | done
- superseded_by: <slug or `none`>

## Binding rules

- Binding rules:
  - A requirements artifact is a candidate primary source only when one of these holds:
    - the user explicitly names the artifact
    - `.opencode/work/current-task.md` points to it
    - `task_slug` matches the current task
  - A candidate primary source becomes primary only when `status` is not `superseded`,
    `base_commit` is valid for the current repository state, and `superseded_by` is `none`
    or absent.
  - If `status` is `superseded` or `base_commit` is unknown or stale, do not use the file as
    primary source.
  - If `superseded_by` is present, inspect that artifact next as the preferred candidate
    source.
  - If none of the explicit binding conditions hold, treat the file as reference material
    only.

## Atomic requirements

### R-1: <short label>

- Type: capability | constraint | quality
- Normalized statement: <EARS-style statement or precise equivalent>
- Source: <where the requirement comes from>
- Target: <system, file, behavior, or artifact being changed>
- Desired change: <what must change>
- Invariants: <what must remain true>
- Constraints: <boundaries on the solution>
- Acceptance criteria: <measurable done conditions>
- Verification method: <how to confirm the requirement>
- Affected tests: <tests to add, update, check, or `None identified.`>
- Affected docs: <docs to add, update, check, or `None identified.`>
- Attribute status:
  - source: user_provided | repo_derivable | public_fact | unknown
  - target: user_provided | repo_derivable | public_fact | unknown
  - desired change: user_provided | repo_derivable | public_fact | unknown
  - invariants: user_provided | repo_derivable | public_fact | unknown
  - constraints: user_provided | repo_derivable | public_fact | unknown
  - acceptance criteria: user_provided | repo_derivable | public_fact | unknown
  - verification method: user_provided | repo_derivable | public_fact | unknown
  - affected tests: user_provided | repo_derivable | public_fact | unknown
  - affected docs: user_provided | repo_derivable | public_fact | unknown
- Field grounding:

  | Field               | Source class                                           | Claim authority                          | Evidence                                                  | Binding level                                                                                   |
  | ------------------- | ------------------------------------------------------ | ---------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
  | Source              | user_provided                                          | binding                                  | user request                                              | binding requirement                                                                             |
  | Target              | user_provided, repo_derivable, public_fact, or unknown | binding, candidate, unknown, or rejected | <path:line, URL, user request, deduction, or `None yet.`> | binding requirement, non-binding candidate, working assumption, blocked, or rejected assumption |
  | Desired change      | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |
  | Invariants          | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |
  | Constraints         | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |
  | Acceptance criteria | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |
  | Verification method | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |
  | Affected tests      | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |
  | Affected docs       | ...                                                    | ...                                      | ...                                                       | ...                                                                                             |

## Claim ledger

Use this only when one field contains multiple material claims or non-trivial derivation.

| Claim id | Field   | Claim   | Status                                                                                                                                      | Evidence                  | Derivation                          | Binding level                                         | Allowed use                                  |
| -------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------------------- | ----------------------------------------------------- | -------------------------------------------- |
| C-1      | <field> | <claim> | user_stated, repo_observed, public_observed, project_rule, deduced, inferred_candidate, working_assumption, unknown, or rejected_assumption | <evidence or `None yet.`> | <deduction or auxiliary assumption> | binding, non-binding, temporary, blocked, or rejected | requirement, investigate only, or do not use |

## Inferred candidate requirements

- <candidate requirement, why it seems plausible, missing evidence or user decision, and why it is non-binding>
- None identified.

## Rejected assumptions

- <assumption that might be tempting but was not adopted, with the reason>
- None identified.

## Execution readiness

- Ready for implementation: yes | no
- Blocking reasons:
  - <unknown, unchecked source class, or candidate claim still present in a binding field>
  - None identified.

## Open questions

- [ ] <only attributes that remain truly unknown>

## Handoff recommendation

- Next capability set: <requirements-clarification | investigation | public-research | task-planning | implementation | refactoring | code-review | epistemic-audit>[, ...]
- Why: <one short explanation>

If a field has no applicable content after discovery, write None identified. rather than leaving it blank.

Procedure

Step 1: Restate the implementation intent

Summarize what change the user appears to want.

Step 2: Discover from local and public context

Read the relevant repository files.

If externally grounded facts affect the requirement record, attach public-research before asking the user.

Step 3: Split the request into atomic requirements

Identify each independent capability, constraint, or quality expectation.

Step 4: Fill the normalized records

For each atomic requirement, fill every field in the template and assign an explicit attribute status.

Also fill the field grounding table for the material fields. Use the claim ledger only when one field contains multiple material claims or a non-trivial derivation. Move plausible but unconfirmed content into Inferred candidate requirements instead of making it part of a binding field.

Step 5: Evaluate unresolved attributes

If unresolved required attributes remain:

• include investigation for repo_derivable
• include public-research for public_fact
• ask targeted user questions only for unknown

If the remaining unknown attributes are tightly interdependent, you may attach grill-me before returning to this artifact.

Step 6: Write the document

Write the current artifact to the output file even if follow-up work remains.

Do not wait for perfection before externalizing the normalized record.

Step 7: Recommend the next capability set

Base the recommendation on the unresolved attributes or, if none remain, on the next real execution need.

Do not force mixed follow-up work into a single capability when different obligations require a capability set. Keep the set as small as possible while still sufficient.

Handoff rules

• include investigation when unresolved required attributes are repo_derivable or a required local source-of-truth class is unchecked
• include public-research when unresolved required attributes are public_fact
• keep requirements-clarification active when unresolved required attributes are truly unknown and user input is still needed
• include epistemic-audit when source-class selection, claim authority, or allowed use is non-trivial
• include task-planning when the requirement records are complete but the work still needs sequencing, decomposition, or a resume-safe artifact
• include implementation when the requirement records are complete and the change can be executed directly
• include refactoring when the complete records describe behavior-preserving structural cleanup
• include code-review when the task is to review code quality rather than to edit

Quick checklist

Before finishing, verify all of the following:

• the user request was treated as a stated requirement, not as instant implementation
• the request was split into atomic requirements
• each atomic requirement has the fixed fields
• each required attribute has an explicit status value
• each material requirement field has grounding for source class, claim authority, evidence, and binding level
• inferred candidates, working assumptions, and rejected assumptions are not used as binding requirements
• execution readiness blocks implementation when a binding field still depends on a candidate claim or unchecked required source
• repo and public discovery were attempted before asking the user
• open questions include only true unknown attributes
• the artifact was written to an external file
• the next-step recommendation names the smallest sufficient capability set