requirements

name	requirements
description	Generate a requirements artifact from the active wiki. Produces quality attributes & constraints for Strategic items; functional requirements with acceptance criteria for Product items.

Skill: Requirements List

You were invoked by the orchestrator because the user wants to generate a requirements list for the active work item. Your job is to extract and structure every requirement present in the wiki — not to invent requirements from your training knowledge.

The orchestrator passed OUTPUT_PATH, WORK_ITEM_TITLE, and WORK_ITEM_TYPE — use those values for all file operations and document metadata.

Follow every step in order.

Buddy mode

By default this skill runs non-interactively — it writes the artifact without pausing for confirmation.

If BUDDY_MODE = true was passed by the orchestrator, pause at confirmation steps and wait for user input before writing.

⚠️ Language lock: Write the entire artifact — content, headings, table values, and all messages — in {LANGUAGE}. Source documents may be in a different language; never mirror them. This constraint is active from the first character to the last, throughout every step.

---

Step 1 — Verify content sources

Attempt to read {OUTPUT_PATH}index.md (the local wiki index for this work item) and check whether {CONTEXT_PATH} is non-empty.

Determine the content situation using the table below:

{OUTPUT_PATH}index.md	{CONTEXT_PATH}	Action
exists and has entries	any	Set LOCAL_WIKI = true. Note the total number of pages listed (sources, concepts, entities).
missing or no entries	has content	Set LOCAL_WIKI = false. Warn the user: "No sources ingested for this work item — proceeding with upstream context only."
missing or no entries	empty or absent	Stop. Tell the user no sources have been ingested and there is no upstream context. Suggest running /ingest first.

---

Step 2 — Determine the requirements mode

Check {WORK_ITEM_TYPE} (from the orchestrator context):

Work Item Type	Mode
Theme, Initiative	Constraints mode — extract quality attributes, architectural constraints, and compliance obligations
Epic, Feature	Functional mode — extract functional requirements with acceptance criteria

Proceed in the corresponding mode for all subsequent steps.

---

Step 3 — Read all content sources

If LOCAL_WIKI = true, read in this order:

1. docs/wiki/overview.md — global synthesis (read directly)
2. All sources/ pages listed in {OUTPUT_PATH}index.md — follow each link to load from docs/wiki/
3. All concepts/ pages listed in {OUTPUT_PATH}index.md
4. All entities/ pages listed in {OUTPUT_PATH}index.md

If {CONTEXT_PATH} is non-empty, read all files present in {CONTEXT_PATH} after completing the local wiki list (or as the sole source if LOCAL_WIKI = false). These are upstream artifacts from the parent work item:

• In NFR mode: upstream requirements.md from a grandparent Strategic item defines pre-existing constraints — do not contradict them, reference them.
• In Functional mode: upstream requirements.md (NFR), brief.md, and feature-list.md set the frame — functional requirements must stay within those boundaries.
• Note each upstream source when carrying a fact forward.

In Constraints mode, extract:

• Performance, scalability, reliability, availability targets
• Security and privacy requirements
• Compliance and regulatory obligations
• Interoperability and integration constraints
• Architectural principles or guardrails explicitly stated

In Functional mode, extract:

• Capabilities the system must provide
• Rules and validations described in sources
• Explicit user interactions or flows described
• Data requirements (fields, formats, volumes)
• Integration points with other systems
• Out-of-scope statements (exclusions are requirements too)

Track the source wiki page for every requirement you find. Never create a requirement not backed by a wiki page or upstream artifact.

---

Step 4 — Confirm scope with the user

Before writing, list what you found:

Based on the wiki ({N} pages), I found:

• {N} requirements to document
• {N} requirements backed by multiple sources
• {N} areas with no coverage (gaps)

Categories detected: [list]

Is there anything you want excluded, rephrased, or split differently?

Default mode: Proceed immediately with your judgment. Do not wait for a response.

Buddy mode: Wait for a response. If the user says "go ahead", proceed.

---

Step 5 — Lock the output language

Before writing any file, resolve and declare the language that will be used throughout:

1. Read {LANGUAGE} from the parameters passed by the orchestrator.
2. Map to the expected locale:
   • pt-BR → Brazilian Portuguese
   • en → English
   • anything else → English (and warn the user)
3. If {LANGUAGE} is not set or is empty, default to en and warn: "LANGUAGE was not set — defaulting to English."
4. State the resolved language explicitly before proceeding:

Output language locked: {resolved language} ({LANGUAGE})
All artifact content, headings, and messages will be written in this language.

Do not begin writing any file until this step is complete. This prevents language drift across multiple generated files.

---

Step 6 — Write the requirements artifact

Create {OUTPUT_PATH}artifacts/requirements.md.

Use locales/{LANGUAGE}/template.md if it exists (e.g., locales/pt-BR/template.md when {LANGUAGE} is pt-BR); otherwise fall back to template.md.

• Use Constraints Mode Template when {WORK_ITEM_TYPE} is Theme or Initiative.
• Use Functional Mode Template when {WORK_ITEM_TYPE} is Epic or Feature.

Fill all placeholders, preserve section order, and do not add, remove, or change the count or hierarchy level of headings.

Validation runs automatically via hook after each Write or Edit. If a validation error appears in context, fix the artifact before proceeding. Do not update navigation files or report success before all errors are resolved.

---

Step 7 — Update navigation files

{OUTPUT_PATH}index.md — add or update the ## Artifacts section:

## Artifacts

- [[artifacts/requirements]] — Quality Attributes & Constraints (generated YYYY-MM-DD)

{OUTPUT_PATH}log.md — append one entry at the top:

## [YYYY-MM-DD] artifact | Requirements ({mode})

Generated: artifacts/requirements.md
Mode: {Constraints | Functional}
Requirements documented: N
Gaps flagged: N
Sources read: N pages

docs/forge.yaml — register the artifact in the work item entry:

1. Find the entry whose path matches {WORK_ITEM_PATH}.
2. If it has no artifacts field, add one as an empty list.
3. If requirements is not already in the artifacts list, append it.

Use the Edit tool. Example — before:

  - title: my-work-item
    hierarchyLevel: Strategic
    path: docs/strategic/initiatives/20260504-my-work-item/

After:

  - title: my-work-item
    hierarchyLevel: Strategic
    path: docs/strategic/initiatives/20260504-my-work-item/
    artifacts:
      - requirements

If artifacts already exists, append requirements to the list. Never duplicate an entry already present.

---

Step 8 — Close the loop

Done. Requirements artifact generated at {OUTPUT_PATH}artifacts/requirements.md.

Mode: {Constraints | Functional}
Requirements documented: N
Gaps flagged: N (sections without wiki coverage)
Sources read: N pages

Anything you want me to revise?

---

Rules

• Write all content in {LANGUAGE}. If LANGUAGE is pt-BR, write in Brazilian Portuguese. If LANGUAGE is en, write in English. Apply this to artifact content, section headings, and all messages shown to the user. If LANGUAGE is not set, default to English.
• Never create a requirement not backed by a wiki page. Use > [!gap] for areas the wiki does not cover.
• Never write to wiki pages in docs/wiki/. This skill is read-only on the wiki.
• Never skip Step 4. The user must confirm scope before you write a long structured table.
• Never skip Step 5. Language must be locked before any file is written — never assume or infer the language mid-generation.
• Priority values are Must / Should / Could / Won't only. Do not use numeric scales unless the wiki explicitly states them.
• Each requirement gets its own row. Do not bundle multiple requirements into one row.
• Source citation format: use [[sources/slug]], [[concepts/slug]], or [[entities/slug]] for local wiki pages. For files read from {CONTEXT_PATH}, substitute the actual runtime value and write the full repo-relative path: [[docs/strategic/initiatives/20260504-foo/output/artifacts/brief.md]]. Never use short names ([[brief.md]]) or computed relative paths ([[../../...]]) for cross-work-item references — they resolve to the wrong location.