Intent Layer

Intent split across notes and books gives no single answer to the question an agent asks before building. One home per kind, with the product record, goals, problems, constraints, decisions, research, actors and journeys at product level and each module with its goals, problems, constraints, decisions, research and features under its module folder, gives every reader one place to look. A second home for any kind starts a second truth about the product. The folder is the parent: product level holds only the product, actors, roles and journeys, module level holds only features with their requirements, and goals, problems, constraints, decisions and research sit at either level with the folder saying which. Each module folder names a module declared in Behavior, so one name runs through Intent, Behavior and code.

Checked bylitespec model check reports a blocking finding for a record outside its home, a folder under intent/modules/ naming no declared module, a module folder without its module, a record type outside its allowed levels, and a link from another module to a module-local record.

Marked checkable: the tool named here checks it.

One product record gives every reader one answer to what the product is and who it serves. The boundary and addresses focus every later choice. Two product statements let each plan cite the one it prefers. summary states what the product is in one place.

Checked bylitespec model check reports no product-count-invalid finding, and litespec model check reports record-invalid for product fields outside the record schema.

Marked checkable: the tool named here checks it.

LiteSpec specifies the product, not the company. Prices as an offer, markets, hiring, sales actions, launch calendars, company goals and founder concerns can be checked only against a bank account, a diary or a contract, so they sit outside the records a reader reviews as the product. A company fact that binds the product still enters: as a constraint when an authority or a limit binds the application, and as dated research when a choice rests on it. The Software Test names what belongs for each record type: a goal states a software outcome, a problem states a user pain the software answers, a feature states a capability the software has, and a module names a product area, never a company function. Plan entitlements the software enforces stay, as settings and permissions; the price list as a company offer leaves.

A library holds its lending limit as a setting the application enforces, so the limit stays as Behavior. The membership price the library charges as an offer is a company fact: it enters only as dated research behind the decision that sets the limit.

Reviewed forIntent and Behavior records stating company operation beside the constraints and research that carry the binding facts.

Marked guidance: a reviewer answers this question.

The folder fixes where a record sits. Reachability fixes that it leads to software. A goal reaches a journey or a quality requirement. A problem reaches a feature or a requirement that addresses it. A feature or a requirement reaches a use case, a journey or a quality scenario in Behavior. A constraint is answered by a requirement. Research is cited by a record that reaches Behavior. A decision decides a record that reaches Behavior. A record that reaches no Behavior is either unfinished work for the backlog or not software.

Checked bylitespec model check reports a blocking finding for a record that reaches no Behavior.

Marked checkable: the tool named here checks it.

A goal without a measure is a wish no check can confirm: the team cannot tell whether the product serves it. The summary states what the goal is in one paragraph, the statement names the outcome and why it matters, and measure and target name what is counted and the number aimed for. A goal carries no authority: it explains why features exist and never decides a conflict.

Checked bylitespec model check reports record-invalid for a goal record file missing a required field.

Marked checkable: the tool named here checks it.

A goal no journey serves and no quality requirement confirms names an outcome the product never touches: a company hope filed as a product goal. A journey serving the goal shows the walk that moves the counted outcome, and a quality requirement citing it states the measure that confirms the move. An outcome the system controls directly is a quality requirement, and an outcome only the company controls is no goal at all.

The library goal of faster pickup is moved by the borrow-and-return journey serving it; a goal of higher membership sales is moved by no journey and is no product goal.

Checked bylitespec model check reports goal-mover-missing for a goal moved by no journey and no quality requirement.

Marked checkable: the tool named here checks it.

A problem is a pain someone outside the team has today. The first affects entry is the primary sufferer, so who has the pain is the first fact a reader meets. statement states the sufferer, the condition and the consequence in one sentence, with the product never as its subject. summary states what the pain is in one paragraph: when it happens and what the person was trying to do, and never stands as a bare pointer to another page. What is no problem leaves for its own record: a solution in disguise becomes a feature, a worry about what might happen becomes a decision or a goal, an internal limit becomes a limit on the plan written outside Intent, a market fact becomes research, and a legal duty becomes a constraint.

In the library product, readers losing track of due dates is a problem whose primary sufferer is the reader. The library having too few staff for the summer is an internal limit and no problem.

Checked bylitespec model check reports problem-sufferer-invalid for a problem whose primary sufferer is no person or organization outside the team; litespec model check reports record-invalid for a problem record file missing affects, summary or statement.

Marked checkable: the tool named here checks it.

A pain with no cost and no workaround is a slogan: no reader can tell a daily loss from a passing annoyance, and no feature can be judged against the price of standing still. The workaround shows the pain is real enough to work around, and why that workaround fails. Where nobody has priced the cost or named the workaround, unknown states the gap honestly. Who Has It states the cost and What They Do Today states the workaround, so the fields stay checkable and the context stays readable.

A reader who loses track of due dates pays late fees each month, and keeps a paper list of due dates, which fails when the list stays at home.

Reviewed forThe cost and the workaround, each in the sufferer's own units or the word unknown, in Who Has It and What They Do Today of each problem explanation file.

Marked guidance: a reviewer answers this question.

Evidence states how anyone knows the pain is real: observed means a sufferer was watched, reported means a sufferer said it, and assumed means nobody outside the team has confirmed it. The strength of a problem is the strongest kind present, computed by the builder and never written, so it cannot drift from the entries. A problem resting on assumption alone, or on no entry, is unfinished work for the backlog until a sufferer is watched or heard.

The library problem of readers losing due dates carries a reported entry from the desk log, read on its date, so its computed strength is reported.

Checked bylitespec model check reports problem-evidence-missing for a problem with only assumed evidence or none. The builder writes evidenceStrength on each problem in the model.

Marked checkable: the tool named here checks it.

A statement naming a solution files a missing feature as a pain: the reader accepts the answer before weighing the pain, and every alternative answer reads as off-topic. A statement naming the sufferer, the condition and the consequence leaves the answer to the feature that solves it.

"Readers lose track of due dates" names a pain. "Readers need a reminder dashboard" names a solution and is reported.

Reviewed forWhich problem statements name a product, a feature, or a solution? Look at the problem statements beside their sufferers.

Marked guidance: a reviewer answers this question.

Two pains of one sufferer under one feature, written in different words, hide that they are one pain or two: one feature solves both halves, and the book lists the sufferer twice with no sign of the overlap. Naming the sibling states the split where a reader meets it; merging keeps one pain with one sufferer.

Two library problems of the reader cited from the borrowing feature, one on due dates and one on renewals, name each other, so a reader sees both before the feature solves either.

Reviewed forWhich problems share a sufferer and a feature yet name neither each other nor a merge? Look at the problems cited from each feature.

Marked guidance: a reviewer answers this question.

The fields state who suffers; the explanation carries the cost, the one concrete occasion, the workaround in use, the evidence behind each claim, and what change in the world would retire the pain. A fixed order means a reader who learned one problem page finds each part on every problem page.

The library problem on due dates opens Who Has It with one reader at the desk with three overdue copies, and closes with What Would Retire It: readers holding their due dates without a paper list.

Reviewed forThe four sections, in order, in each problem explanation file.

Marked guidance: a reviewer answers this question.

A problem that names what its people face points to the pain its solution lifts. summary describes the pain in the people's own terms, and the graded evidence shows it is real. Problems without sufferers attract solutions nobody needs. The affects link names the actors who face it, so each pain traces to the people a solution must serve.

Checked bylitespec model check reports record-invalid for a problem record file missing its summary or statement.

Marked checkable: the tool named here checks it.

A feature names the problems it solves in solves and the goals it moves in advances, so each offer traces to a pain and an outcome. offering states what is in and what is out, so the scope of the offer is written where the links are. Proposed by decision/0004-features-advance-goals on the evidence in research/intent-hierarchy-evidence, research/cross-layer-trace-evidence, and research/established-traceability-practice.

Reviewed forWhich features miss their offering, their solved problems, or their moved goals? Look at each feature record beside its problems and goals.

Marked guidance: a reviewer answers this question.

An actor answers for what it does, so software stands behind no actor: an external system stands alone as its own record, and internal machinery such as a reaction, a job, a transport or a renderer is never an actor. A person or an organization can hold a role, suffer a problem and walk a journey. belongsToTeam reads as a predicate that is true about the record, so a reader tells a team actor from a customer at a glance, and a problem can refuse a team sufferer.

The library reader is an actor of kind person with belongsToTeam false. The text gateway is an external system and no actor.

Checked bylitespec model check reports record-invalid for an actor record file with a kind outside person and organization, or with no belongsToTeam; litespec model check reports field-invalid for such a kind.

Marked checkable: the tool named here checks it.

An actor named by nothing is a party nobody suffers as, walks as or grants to: a leftover from a system or a machine promoted beside real people. Naming each actor from the walk it walks, the pain it suffers or the role it holds keeps the actor list equal to the parties the product serves.

The library reader is named by the borrow-and-return journey and by the due-date problem; the librarian is named by the holds of the librarian role.

Checked bylitespec model check reports actor-unused for an actor named by no journey, problem or access position.

Marked checkable: the tool named here checks it.

A phrase used across records reads as a defined term whether or not any definition exists: readers and agents build on a meaning nobody wrote. Flagging the phrase while it is still cheap to define keeps the glossary equal to the words the records actually use.

A library phrase naming its first lending partners, used across goals and problems, takes a glossary term stating who those partners are, or the records stop using the phrase.

Checked bylitespec model check reports term-missing for a capitalized phrase of two to four words named in three or more records that no glossary term defines.

Marked checkable: the tool named here checks it.

An unanswered constraint is an outside rule the product can break unknowingly: a law, a regulation, or provider terms the team never examined. Recording each rule with its authority and applicability proves the team asked. The kind is technical, organizational, convention, or legal. summary states the rule in the authority's own words, readOn states when the outside rule was read, and What It Requires lists the requirements that cite the constraint, generated at build time. A fact learned from the world, such as the payout bank lengthening its settlement window, first lands as research with its source and date, then as a constraint.

Checked bylitespec model check reports record-invalid for a constraint record file missing a required field; the builder generates What It Requires from citing requirements.

Marked checkable: the tool named here checks it.

A fact without its source cannot be rechecked when a decision depends on it. The read date shows when the outside fact was true, so a later reader knows whether to trust or refresh it. Research without sources and dates asks every later choice to rest on memory. The conclusion states in one sentence what the sources establish and what follows, so a decision can cite it as data. Each source carries its key, url, and readOn; the explanation cites a source with a reference link [text][key], and a bare URL, an unknown key, or an unused source is a finding. Answer expands the conclusion: what the sources say, claim by claim, with the confidence behind each claim, and Notes on Sources holds what a later reader needs about each source. Observed provider behavior lands here too, cited and dated, before any constraint or requirement rests on it. Proposed by decision/0009-research-states-its-conclusion on the evidence in research/research-conclusion-evidence.

Checked bylitespec model check reports record-invalid for a research record file without question, conclusion, or sources; litespec model check reports explanation-missing for a research record without Answer in its explanation file, source-link-bare for a bare URL, source-key-unknown for an unknown key, and source-unused for an unused source.

Marked checkable: the tool named here checks it.

Context in the explanation file states the choice, choice names the chosen option, and consequences states what follows, so each decision reads the same way. Decision in the explanation file expands the chosen option, and Evidence with Confidence holds the supporting material with its confidence where the choice rests on it. The reopenedWhen condition names what would reopen the choice, so a decision reopened by a condition rather than a date stays stable until the world actually changes. The basedOn link names the constraints and research behind it, and requirements only on a technical decision. The model page requires each product decision to name the records it settles in decides.

Checked bylitespec model check reports record-invalid for a decision record file missing a required field; litespec model check reports explanation-missing for a decision without Context in its explanation file.

Marked checkable: the tool named here checks it.

A choice argued from options and evidence can be revisited on its merits; one argued from authority cannot. Each option carries its name with what speaks for it in pros and against it in cons, so the comparison sits in the entries instead of a prose section.

Checked bylitespec model check reports record-invalid for a decision option missing pros or cons.

Marked checkable: the tool named here checks it.

The module names one product area of the bounded context, so Intent, Behavior and code share one name for one area. summary states what the area covers in one place, and dependsOn names the modules it builds on. A reader learns where each area sits once and finds its records under one folder. Cross-cutting work sits at product level, never in a module that borrows it.

The spending module covers expenses, receipts and the policy, with an empty dependsOn where it stands alone.

Checked bylitespec model check reports record-invalid for a module record file missing a required field.

Marked checkable: the tool named here checks it.

An identifier lets a Behavior record name the commitment it fulfills and lets the model resolve the name. A commitment written only as prose cannot be traced from Intent to code. The feature segment names the feature holding the entry, and the feature is the parent by identifier containment. Proposed by decision/0003-requirement-origin on the evidence in research/intent-hierarchy-evidence, research/cross-layer-trace-evidence, and research/established-traceability-practice.

Checked bylitespec model check reports record-invalid for a requirement entry without identifier; litespec model check reports identifier-invalid for a feature segment differing from its feature.

Marked checkable: the tool named here checks it.

The kind is functional, quality, or policy: what the product does, how well it does it, or what the business holds. A policy requirement carries its values with effective dates. The statement states the commitment in one testable sentence.

Checked bylitespec model check reports record-invalid for a requirement entry without kind or statement, or a policy requirement without dated values.

Marked checkable: the tool named here checks it.

The cites list holds any of goal, problem, feature, constraint, research, and decision, in no order of precedence. The feature holding the entry is the parent; the cited reasons are connections that explain why the commitment exists. A requirement that cites nothing reports as requirement-cites-missing.

Checked bylitespec model check reports requirement-cites-missing for a requirement entry naming no reason in cites.

Marked checkable: the tool named here checks it.

An applying constraint with no citing requirement has no answer the product keeps. Citing it ties the outside rule to the commitments that obey it, and What It Requires lists those commitments back. A constraint with applies: true that no requirement cites reports as constraint-unreached at check level G.

Checked bylitespec model check reports constraint-unreached for a constraint with applies: true that no requirement cites.

Marked checkable: the tool named here checks it.

A commitment without its reason cannot be rejudged when the world moves: the reader finds what holds but not why. One line forces the reason into the open without inviting an essay. The feature carries the full story; the rationale carries the reason beside the commitment.

Reviewed forThe one-line rationale on each requirement entry.

Marked guidance: a reviewer answers this question.

A number without its measure cannot be checked: the team cannot tell what is counted. The measure names what is counted. A requirement carrying measure needs a check and a passing run, and a statement naming a number with no measure reports at check level A.

Checked bylitespec model check reports requirement-measure-missing for a requirement carrying measure without check or a passing run, and for a statement naming a number with no measure.

Marked checkable: the tool named here checks it.

"Fast", "secure", or "always available" cannot be built to or checked. A quality requirement holds only for a moment that can happen: something arrives, under some condition, and the product answers within a measure. Written that way, it tells the builder what to design for and tells a test or a probe what to look for, and a later change in the moment (a bigger on-sale, a new attack) visibly reopens the target. The four fields follow the quality attribute scenario the architecture literature uses, so a reviewer can compare one target with another. The check names the probe or test that confirms the measure, and it is required where the requirement carries measure. The target names the number aimed for, conditions names what holds while measuring, runsOn names where the check runs, and evidence names what the run leaves behind; each applies where the confirmation needs it.

requirement/expense-submission.month-end-submissions has kind: quality, stimulus "Five hundred employees submit expenses in the last hour of the month", environment "Normal operation, one application instance down", response "Each submission is stored and acknowledged", measure "Share of submissions acknowledged within two seconds: at least 99 percent", and check "month-end acknowledgement probe".

Checked bylitespec model check reports record-invalid for a quality requirement missing stimulus, environment, response, measure, or check.

Marked checkable: the tool named here checks it.

The records that fulfill are rule, use case, reaction, job, notification, and setting. A journey names the requirements it shows in cites; it never fulfills, so a journey alone never clears an unfulfilled requirement. Behavior points up to the promises it keeps, and each promise traces down to the behavior that keeps it.

Checked bylitespec model check reports requirement-fulfillment-missing for a requirement no Behavior record fulfills.

Marked checkable: the tool named here checks it.

A journey names its actor, its goal record in serves, its finishedWhen, and its ordered steps. One actor means a step names another actor only at a handoff; one goal means a walk with several goals splits into several journeys. The order shows how the steps join toward the goal, so a step that fits nowhere is visible. The journey names in cites the requirements it carries, and the use cases, reactions, and jobs that serve each step point up with serves. betweenSteps holds branch order only, and Example in the explanation file shows one concrete occasion. Proposed by decision/0005-journeys-serve-a-goal on the evidence in research/intent-hierarchy-evidence, research/cross-layer-trace-evidence, and research/established-traceability-practice.

The largest consumer held a 21-step journey with five actors, from creating the organizer to closing the books. Split by goal, it is four journeys: set up and sell an event; buy a ticket; admit the crowd; close the night.

Checked bylitespec model check reports record-invalid for a journey record file missing its actor, serves, summary, finishedWhen, steps, or betweenSteps.

Marked checkable: the tool named here checks it.

A journey page opens with its steps, so a reader landing on it cold learns the mechanics before the purpose. The summary states the walk in the walker's terms first, and the book renders it first on the page. finishedWhen stays the checkable end state; the summary carries the purpose no field checks.

The library journey to borrow and return describes a reader who holds a copy, starting at the shelf and ending with the copy back on its shelf, because a reader plans the next visit around the return.

Checked bylitespec model check reports record-invalid for a journey record file missing summary.

Marked checkable: the tool named here checks it.

A step performed by machinery forced a machine actor into Intent, where it sat beside real people and held no role. Naming the system record that performs the step keeps the actor list to people and organizations, and keeps the performing party one link away. A step naming both an actor and a system names two performers for one act.

In the library journey, the step that sends the overdue notice names the text gateway in system; the steps the reader walks name no performer.

Checked bylitespec model check reports record-invalid for a journey step carrying both actor and system; litespec model check reports field-invalid for such a step or for a system naming no external system, job or reaction.

Marked checkable: the tool named here checks it.

An Intent record that names Behavior detail becomes a second specification, and it drifts from the first with the next Behavior change. Two specifications force every reader to ask which one the code follows. Behavior records own behavior and point up to the requirements and steps they serve, so each fact has one home.

Reviewed forIntent records under .litespec/intent/ free of the detail the Statement names.

Marked guidance: a reviewer answers this question.

Records generated outside docs/ mix verified facts, inferences, and recommendations in one confident voice. Treating them as source material with no authority keeps a recommendation from being built as if someone decided it. A research record or a decision restates the claim before anything rests on it.

Reviewed forA research record or a decision behind each position built from generated records.

Marked guidance: a reviewer answers this question.

An exception without a fallback leaves the reader at the exact moment the promise breaks: the product refuses with no stated alternative. The condition states in product words when the commitment does not hold, and fallback names the requirement that covers what happens then. The fallback carries no except of its own, so the chain stays one deep and every exception ends in a promise.

A reimbursed expense lands in the employee's account, never more than they spent. Except when the payout bank's settlement window has closed for that batch, with fallback naming the requirement that has finance repay the employee by other means.

Checked bylitespec model check reports no except-fallback-missing finding.

Marked checkable: the tool named here checks it.

A step written as a product sentence reads in journey detail with no Behavior knowledge: it states what a person experiences, not which handler runs. The id (s1, s2, and so on) gives Behavior a stable target: use cases, reactions, and jobs point up with serves to journey/<name>#s1. A step that names its use case drags Behavior into Intent and breaks the journey detail every time Behavior renames. The performer and the failure text are optional: a step names the walking actor only at a handoff in actor, or the system record performing it in system when no person acts, and carries failure where the walk can fail.

Step s4 states Finance reimburses the approved expense. in statement and names no use case; use-case/spending.reimburse-expense names journey/submit-and-reimburse#s4 in serves.

Checked bylitespec model check reports record-invalid for a journey step missing id or statement, or naming a use case.

Marked checkable: the tool named here checks it.

A journey without a stated end can stop anywhere: the reader cannot tell a finished walk from an abandoned one, and serving records cannot tell done from dropped. finishedWhen states the observable end in one sentence, in product words.

finishedWhen: the employee holds the reimbursement.

Checked bylitespec model check reports record-invalid for a journey record file missing finishedWhen.

Marked checkable: the tool named here checks it.

Tenants choose their own values within the ranges Intent sets: a tenant holds its receipt threshold at EUR 25 by default within the EUR 0 to EUR 500 range. The requirement sets the range and the default, and each tenant's choice inside it is data. Treating tenant values as product values would bind every tenant to one tenant's choice.

The tenant sets a receipt threshold of EUR 50; the requirement covering threshold ranges already sets the range, so the threshold itself is data.

Reviewed forEach setBy: tenant value stored as tenant data.

Marked guidance: a reviewer answers this question.