docs(rules): write a Spec around its objects and key results

docs/rules/DEV-125.md

@@ -4,14 +4,14 @@ title: "Write a Spec in the Standard Format"
 status: "active"
 enforcement: "manual"
 severity: "error"
-depends_on: ["DEV-180", "DEV-350"]
+depends_on: ["DEV-180", "DEV-350", "DEV-390"]
 ---
 
 ## Problem
 
 A Spec written without a shared structure is hard to read and review: readers
-cannot tell where the goal, the overview, or the behavior sections are, and
-specs drift into describing internals instead of user behavior.
+cannot tell where the objective, the user types, or the behavior sections are,
+and specs drift into describing internals instead of user behavior.
 
 ## Solution
 
@@ -21,19 +21,39 @@ about what users can do, not how the system works.
 1. Store the Spec as a markdown file under `docs/specs/`, linked from its Goal
    under `# Spec`; its sections graduate to `docs/product/` per
    [DEV-180](./DEV-180.md).
-1. Start with `goal:` frontmatter linking the Goal, then an H1 feature name and
-   a `## Overview` of what the Goal enables for users.
-1. List every user type in `## User Types`, including operator and administrator
-   types that are not the client's end-users. If a type's account is provisioned
-   outside the product (database seed, manual setup), say so, and say whether
-   the product can create more of them.
-1. Treat the user account as a key concept, not as a separate administration
-   area: creating, listing, granting access to, and removing accounts are
-   actions on it like any other.
-1. Name the permitted user type in every action. An action with an implicit
-   actor cannot be reviewed against what the product actually allows.
-1. Add author-defined `##` sections that describe observable user behavior, not
-   internal mechanics.
+1. Carry only what is new: behavior the Goal adds or changes. Where the product
+   docs already explain something the Spec refers to, such as a user type, an
+   object, a capability, or a term, do not explain it again: name it as the
+   product docs do and link to the section that explains it.
+   [DEV-390](./DEV-390.md) keeps that section matching the product. The product
+   docs change only when behavior ships, per [DEV-180](./DEV-180.md), not when
+   the Spec is written.
+1. Start with `goal:` frontmatter linking the Goal, then an H1 feature name of
+   at most 30 characters. Name the feature as a noun phrase, not a sentence.
+1. State in `## Objective`, in at most 250 characters, the business value and
+   the user problem it solves.
+1. List exactly three `## Key Results` as a numbered list, each at most 160
+   characters. Each is a measurable outcome, and together they define success.
+1. List every user type the Spec's actions name in `## User Types`, including
+   operator and administrator types that are not the client's end-users. A type
+   the product docs already explain is named and linked to that section, with
+   nothing explained again. A new or changed type gets, in at most 150
+   characters, its definition and who creates the account: another user type,
+   the user by signing up, or a process outside the product such as a database
+   seed or manual setup. For an account created outside the product, say whether
+   the product can create more.
+1. Give each object users interact with its own `##` section, starting with
+   `## User Account`. Treat the user account as an object, not as a separate
+   administration area: creating, listing, editing, granting access to, and
+   removing accounts are actions on it like any other.
+1. Give each capability on an object its own `###` subsection, named for what
+   the user does, such as "Funding an account".
+1. Write each action as its own item that starts with the user types permitted
+   to perform it: `- [User Type], [User Type] can [action].` An action with an
+   implicit actor cannot be reviewed against what the product actually allows.
+1. Describe observable user behavior, not internal mechanics.
+1. Keep the template's guidance in HTML comments. They do not render, so a
+   partly written Spec shows readers only its content.
 1. Include a `## Design` section using the markup in [DEV-350](./DEV-350.md)
    when the Goal has a design component.
 
@@ -42,40 +62,94 @@ about what users can do, not how the system works.
 goal: <link to Goal issue>
 ---
 
-# Feature Name (max 45 chars)
+# [Feature Name]
+
+<!-- Constraint: Maximum 30 characters, including spaces. A noun phrase, not a sentence. -->
 
 ## Objective
-(describes business objective, max 250 chars)
 
-## Key results
-(three items; max 160 chars each)
+<!-- Constraint: Maximum 250 characters, including spaces. -->
+<!-- Description: The high-level business value and the user problem it solves. -->
+
+## Key Results
+
+<!-- Constraint: Exactly three items, as a numbered list. Maximum 160 characters per item. -->
+<!-- Description: Measurable outcomes that show the Objective is met. Together they are the definition of success. -->
+
+1. [Key Result 1]
+1. [Key Result 2]
+1. [Key Result 3]
 
 ## User Types
-(list of every user type and its short definition, operators and
-administrators included; each item max 150 chars. Note any type whose
-account is provisioned outside the product, and whether more can be
-created in the product)
 
-## Key Concepts
+<!-- Constraint: Bulleted list. Maximum 150 characters per item. -->
+<!-- Description: Every user type the actions below name, operators and administrators included. For a type the product docs already explain, link to that section and explain nothing again. For a new or changed type, give the definition and who creates the account. For an account created outside the product, also say whether the product can create more. -->
+
+- **[User Type]:** Defined in [the product docs](../product/[page].md#[user-type]).
+- **[User Type]:** [Definition]. Created by [User Type, or self sign-up].
+- **[User Type]:** [Definition]. Created outside the product by [database seed, manual setup]. The product [can, cannot] create more.
+
+## User Account
+
+<!-- Description: Required object. Accounts are managed here like any other object, not in a separate administration area. Keep only the capabilities this Goal adds or changes. For the rest, link to the section of the product docs that explains it, and explain nothing again. -->
+
+Defined in [the product docs](../product/[page].md#user-account).
+
+### Creating an account
+
+- [User Type], [User Type] can create a [User Type] account.
+
+### Listing accounts
+
+- [User Type] can list [User Type] accounts.
+
+### Editing an account
+
+- [User Type] can edit a [User Type] account's [details].
+
+### Granting access
+
+- [User Type] can grant a [User Type] account access to [Object].
+
+### Removing an account
+
+- [User Type] can remove a [User Type] account.
+
+## [Object Name]
+
+<!-- Description: A core entity or concept the user interacts with (e.g., "Invoice", "Project"). Repeat this section for each distinct object. Keep only the capabilities this Goal adds or changes. For the rest, link to the section of the product docs that explains it, and explain nothing again. -->
+
+Defined in [the product docs](../product/[page].md#[object-name]).
 
-(subsections describing key concepts users need to know about; the
-relevant methods (actions) each permitted user type can use. Include the
-user account itself as a concept, with its create, list, access, and
-remove actions. Name the permitted user types in every action)
+### [What the User Does]
 
-## [Section]
+<!-- Description: A capability on the parent object, named for what the user does (e.g., "Funding an account"). Repeat this subsection for each capability. -->
+<!-- Constraint: One item per action. Every item starts with the User Types allowed to perform it. -->
 
-Describe what users can do, not how the system works internally.
+- [User Type], [User Type] can [action].
 ```
 
 ### Acceptance Criteria
 
-- [ ] The Spec is a `docs/specs/` file with `goal:` frontmatter, an H1 name, and
-  a `## Overview`
-- [ ] `## User Types` covers every type, operators and administrators included,
-      states how any externally provisioned account comes into existence, and
-      says whether the product can create more of that type
-- [ ] The user account appears in `## Key Concepts` with its own actions
-- [ ] Every action names the user types permitted to perform it
+- [ ] The Spec is a `docs/specs/` file whose `goal:` frontmatter links its Goal,
+      with an H1 noun phrase of at most 30 characters
+- [ ] The Spec carries only what the Goal adds or changes
+- [ ] Nothing the product docs already explain is explained again; the Spec
+      names it and links to the section that explains it
+- [ ] Writing the Spec adds nothing to the product docs
+- [ ] `## Objective` states the business value and the user problem in at most
+      250 characters
+- [ ] `## Key Results` is a numbered list of exactly three measurable outcomes
+      of at most 160 characters each
+- [ ] `## User Types` covers every type the actions name, operators and
+      administrators included, linking types the product docs explain and
+      defining new or changed ones with who creates the account, and, for an
+      account created outside the product, whether the product can create more
+- [ ] `## User Account` is the first object section, covering creating, listing,
+      editing, granting access to, and removing accounts, by content or by link
+- [ ] Each object has its own `##` section with a `###` subsection per
+      capability, named for what the user does
+- [ ] Every action is its own item starting with the user types permitted to
+      perform it
 - [ ] Sections describe user-observable behavior, not internal mechanics
 - [ ] A Goal with a design component includes a `## Design` section per DEV-350