Requirement Forge Refiner

Requirement Forge Refiner

What This Produces

• Output: .lattice/standards/requirement-standards.md (or custom path from .lattice/config.yaml → paths.requirement_standards)
• Two modes:
• Overlay (mode: overlay): A slim document containing only sections that differ from the built-in defaults. The requirement-quality atom reads its embedded defaults.md first, then applies this document's sections on top. This is the expected common case.
• Override (mode: override): A comprehensive standalone document that fully replaces the atom's embedded defaults. For teams whose product process differs fundamentally from the defaults.
• Default mode: Overlay — produces only what the team wants to change
• Config key: paths.requirement_standards in .lattice/config.yaml
• Consumed by: requirement-quality atom (via config resolution) → requirement-forge molecule (composes the atom)
• Template: Read ./assets/template.md for the full document structure, default content, and interview guidance comments

Scope Clarification

This refiner defines how requirements are *structured and expressed* for this project. It does not define:

• What to build (that is the requirement-forge molecule's job)
• Architecture or technical design (that is the architecture-refiner's job)
• Domain modeling patterns (that is the ddd-refiner's job)

The standards produced here answer: what is an epic, what is a feature, what is a scenario, how are ACs written, how are features named and prioritized. These are the rules the requirement-quality atom enforces — the molecule composes the atom and inherits those rules automatically.

Before You Begin

Check for an existing standards document

• Read .lattice/config.yaml — check paths.requirement_standards.
• If the path exists, read that file. Ask the user:
• "You already have a requirement standards document. Would you like to revise it (update specific sections), start fresh (new interview), or add to it (add new sections)?"
• Revise: load the existing document, walk through only the sections the user wants to change, update in place.
• Start fresh: proceed with the full interview flow below.
• Add to it: skip to the "New Sections" part of the interview.
• If no config or no existing document, proceed with the full interview.

Ask two orienting questions first

Before the formal interview, ask:

• "Does your team already have a way of writing requirements — any existing PRDs, Confluence templates, or Jira conventions I should be aware of?"
• "Is there a specific product domain or terminology I should know before we define the standards?"

These two questions are the only free-form listening before the structured interview begins. Synthesize what you hear and carry it forward — do not ask follow-up questions at this stage.

Choosing the Mode

Present the three options:

"How would you like to define your requirement standards?

• Customize specific sections (overlay) — Keep the built-in defaults and change only what differs for your project. This produces a slim document. Most teams choose this.
• Define everything from scratch (override) — Walk through all sections and produce a comprehensive standalone document.
• Add project-specific sections only (overlay with additions) — Keep all defaults as-is and add new sections, such as domain terminology or custom status workflows.

The built-in defaults cover standard product spec practices well. Option 1 is recommended unless your team's conventions are fundamentally different."

Map the choice:

• Options 1 and 3 → mode: overlay
• Option 2 → mode: override

Facilitation Approach

Conversation style

• One section at a time. Do not present all questions at once. Walk through the template sequentially.
• Defaults-first. For each section, briefly summarize the default, then ask if it matches. Do not read defaults verbatim — summarize key points and ask.
• Propose, don't just ask. When the user's answer is ambiguous, propose the most reasonable interpretation and ask them to confirm or correct. "It sounds like you want MoSCoW priorities — so 'Must', 'Should', 'Could', 'Won't'. Is that right?"
• Record decisions, not discussion. The output document reads as a specification. "We discussed X and decided Y" is wrong. "Y" is right.
• Challenge weak definitions. If the user defines a "feature" so broadly it would encompass an entire epic, push back: "That scope sounds like an epic — a feature should be independently designable in one design-blueprint session. Can we tighten the definition?"

For overlay mode

This should be fast. Many sections will be "keep as-is."

• Present each section's default in 2–3 sentences.
• Ask: "Does this match your project, or would you like to change it?"
• If matches → skip it (section will NOT appear in the output).
• If changes wanted → discuss specifics, record the changes.
• After all sections, ask: "Anything to add that isn't covered — domain-specific terminology, custom fields, team conventions?"
• Only changed or added sections appear in the output document.

For override mode

Every section gets attention and appears in the output.

• Walk through every section in full detail.
• User confirms, modifies, or replaces each section.
• All sections appear in the output.

Common scenarios

• "I agree with everything" → No custom document needed. "The embedded defaults are already active. No custom document is needed — requirement-forge will use the defaults automatically."
• "We use MoSCoW priorities" → Overlay §6 only.
• "We call them 'use cases' not 'scenarios'" → Overlay §4 (rename + update any description that references "scenario").
• "We have a longer status workflow" → Overlay §7.
• "We have domain-specific terms that should be consistent" → Overlay with additions — add §10 Domain Terminology.
• "Our features tend to be larger" → Overlay §2 and §4 — adjust the size signals and max scenario count.

Section-by-Section Interview Guide

Read ./assets/template.md and follow the <!-- INTERVIEW GUIDANCE: --> comments for each section. Those comments contain specific questions, probing questions, and what is customizable vs. fixed.

Cross-section dependency table

| Decision in | Affects | How |

|---|---|---|

| §2 — Feature size definition | §4 scenario count | Larger features tolerate more scenarios; tighter features need a lower cap |

| §4 — Scenario nomenclature | §8 naming conventions | If "scenario" is renamed, naming conventions must use the new term |

| §4 — Max scenarios per feature | §2 feature definition | These two must be consistent — the split signal in §2 should align with the cap in §4 |

| §5 — AC format | §4 scenario structure | AC format determines what each scenario's criteria look like |

| §6 — Priority notation | feature file frontmatter | Priority field format used in every generated feature file |

| §7 — Status workflow | feature file frontmatter | Status field used in every generated feature file |

| §8 — Naming conventions | all file generation | Feature file names and display names generated by the molecule |

When a dependency is triggered, inform the user: "Since you changed [X], we should also review [Y] — it's affected by that decision."

Overlay-specific section flow

For each of the 9 default sections:

• Summarize the section's key points in 2–3 sentences.
• Ask: "Does this match your project?"
• Yes → Move to the next section. This section will not appear in the output.
• No → Dive into the details using the template guidance. Produce the user's version.
• After all 9 sections, ask about additions.

Override-specific section flow

For each of the 9 default sections:

• Present the section's full content.
• Ask: "Does this work as-is, or would you like to modify it?"
• As-is → Include the default content unchanged.
• Modify → Discuss changes, produce the modified version.
• All sections go in the output.

Output Assembly

For overlay mode

• YAML frontmatter: mode: overlay
• Overlay preamble (from template)
• Table of contents listing only included sections
• Only the sections the user changed or added — each must be self-contained and complete
• Section headings must match template.md exactly (the molecule matches sections by heading)
• New sections (§10+) included after the default sections
• Footer with project name, date, mode

For override mode

• YAML frontmatter: mode: override
• Override preamble (from template)
• Full table of contents (all 9+ sections)
• All sections: defaults for unchanged, user's version for changed, new sections at end
• Footer with project name, date, mode

For both modes

Strip all <!-- INTERVIEW GUIDANCE: --> comments from the output. The final document is a clean specification.

Determine output path:

• If .lattice/config.yaml exists and has paths.requirement_standards, use that path.
• Otherwise, default to .lattice/standards/requirement-standards.md.

Write the document:

• Create .lattice/standards/ directory (and .lattice/ parent) if it does not exist.
• Write the document to the determined path.

Update config:

• If .lattice/config.yaml does not exist, create it with:

   paths:
     requirement_standards: .lattice/standards/requirement-standards.md

• If .lattice/config.yaml exists but has no paths.requirement_standards, add the key. Preserve all existing content.
• If the key already exists, no config change needed.

Confirm to user:

"Your requirement standards have been written to [PATH] in [overlay|override] mode. The requirement-forge molecule will now use these standards and will not re-ask structural questions covered here."

Document Quality Checks

Before writing the final document, verify:

Overlay mode checks

• [ ] Each included section is self-contained and complete (not a diff or partial section)
• [ ] Section headings match template.md exactly
• [ ] No <!-- INTERVIEW GUIDANCE: --> comments remain
• [ ] Frontmatter has mode: overlay
• [ ] Only changed or added sections are included

Override mode checks

• [ ] All 9 default sections are present (plus any additions)
• [ ] §2 feature size signal is consistent with §4 max scenario count
• [ ] §4 scenario nomenclature is consistent with §8 naming conventions
• [ ] §5 AC format is consistent with how §4 describes scenario criteria
• [ ] §6 priority values and §7 status values match the frontmatter field descriptions in §8
• [ ] No <!-- INTERVIEW GUIDANCE: --> comments remain
• [ ] Frontmatter has mode: override
• [ ] Document is readable as a standalone specification

Both modes

• [ ] Frontmatter is valid YAML with correct mode value
• [ ] Document is well-formatted markdown
• [ ] Config file (.lattice/config.yaml) is correctly updated
• [ ] Output path exists and is writable