Write a Feature Under a Module

Prerequisites#

Start with:

• A consumer from Start a Consumer Repository, with its product brief written.
• The module the feature belongs to, declared at .litespec/intent/modules/<module>/module.yaml.
• The problem the feature answers and the goal it advances, each in its own record file.

Read the Intent page before this guide: it states the obligations, and this guide shows one compliant way to meet them. The command index states how litespec runs in a consumer.

Procedure#

Scaffold the Feature File#

Run litespec new to scaffold the feature: it copies the feature template to .litespec/intent/modules/<module>/features/ and reserves the identifier feature/<name>. Give the feature a kebab-case name, such as feature/expense-submission, and a title in plain words. This satisfies litespec/core/model#write-every-record-in-its-record-file and litespec/core/intent#keep-intent-in-its-homes.

State the Offering and Its Links#

Write offering as one paragraph stating what the software does and for whom. Link the problem the feature answers in solves and the goal it advances in advances, and name the glossary terms the feature uses in terms:

offering: Claimwick takes each expense with its receipt at submission time.
solves:
  - problem/expenses-wait-weeks
advances:
  - goal/faster-reimbursement
terms:
  - term/expense

Write each link on the feature, the record that points. This satisfies litespec/core/model#write-links-on-the-record-that-points.

Write One Entry per Requirement#

Write each commitment the feature makes as one requirement entry under records. Give each entry an identifier of the form requirement/<feature>.<name>, such as requirement/expense-submission.receipt-over-threshold, with its kind, functional, quality, or policy, one testable sentence in statement, one line of reason in rationale, and the records behind it in cites. Cite each applying constraint from the requirement it binds. This satisfies litespec/core/intent#identify-every-requirement, litespec/core/intent#state-requirement-kind-and-statement, litespec/core/intent#cite-the-reasons-of-every-requirement, and litespec/core/intent#cite-each-applying-constraint-from-a-requirement.

records:
  - type: requirement
    id: requirement/expense-submission.receipt-over-threshold
    title: Receipt Over Threshold
    kind: functional
    statement: The product requires a receipt for every expense above the policy threshold.
    rationale: Finance rebuilds spending from forwarded receipts today.
    cites:
      - goal/faster-reimbursement
    except:
      - condition: The amount is under the threshold.
        fallback: requirement/expense-submission.auto-accepted-under-threshold
    setBy: product

State Each Quality Requirement as a Scenario#

A quality requirement carries the scenario that confirms it: the stimulus that triggers it, the environment it holds in, the response the product shows, and the measure, target, and conditions that confirm it. This satisfies litespec/core/intent#state-each-quality-requirement-as-a-scenario.

  - type: requirement
    id: requirement/expense-submission.reminder-delivery-time
    title: Reminder Delivery Time
    kind: quality
    statement: The product delivers every reminder within one hour of schedule.
    rationale: Late reminders push reimbursement past the deadline.
    stimulus: The schedule fires.
    environment: During working hours.
    response: The product sends the reminder.
    measure: Delivery delay per reminder.
    target: Under one hour.
    conditions: Up to ten thousand managers.

State Each Exception with Its Fallback#

A requirement that bends in a named case carries that case in except with its condition and the fallback requirement that holds instead, as the receipt requirement above shows. Name who sets the requirement values in setBy: product, operator, or tenant. This satisfies litespec/core/intent#state-each-exception-with-its-fallback.

Add the Explanation File#

When the feature needs prose beyond its fields, add <feature>.md beside the record file with Who It Serves and Why, What It Offers, and What Good Looks Like. Keep checkable facts in the record file; the explanation file only helps a reader understand. This satisfies litespec/core/model#split-record-fields-from-explanation and litespec/core/model#explain-each-record-beside-its-record-file.

Check#

• litespec model check exits 0 from the consumer root with no finding on the feature file.
• litespec model query feature/<name> shows the feature with its requirement entries.