Skip to content

Change a profile

This guide shows you how to change a profile, the configuration of one doc type, when a review says something you did not mean.

A profile holds the template, the checks, the limits and the policies of one doc type. The frontmatter type: of a spec doc picks the profile. Profile schema lists every key, and the Check catalog lists every built-in check.

  • Local mode. Speccy ships the prd and sdd profiles in the binary. A file in .speccy/profiles/ at the root of the served folder replaces the built-in profile with the same key. It replaces the whole profile, so the file holds every key, not only the ones you change.
  • Hosted mode. The store holds the profiles. On the first start, Speccy copies the built-in profiles into the store. Hosted mode reads no .speccy/profiles/ folder.

speccy review, speccy action and the other commands read .speccy/profiles/ from the folder with .speccy.yaml. Commit the folder, so CI reviews with the same profiles as your machine.

In local mode, you can edit every profile. In hosted mode, an admin or a maintainer of the profile can edit it. Other members suggest a change under Suggestions, and a maintainer applies it.

  1. Choose Profiles in the top bar, and click the profile.

  2. Change the YAML in the left pane, or the template in the right pane. Help explains each key.

  3. Click Save a new version, or press ⌘S. Speccy checks the profile against the schema first. A profile that is not valid stays unsaved, and Speccy lists each error with its path.

In local mode, the save writes .speccy/profiles/<key>.yaml and its template file. The first save of a built-in profile makes the files. In hosted mode, the save writes a new version in the store.

In local mode, you can also write the files yourself.

  • Directory.speccy/
    • Directoryprofiles/
      • sdd.yaml
      • Directorytemplates/
        • sdd.md
  1. Put the profile in .speccy/profiles/<key>.yaml. Start from the whole built-in profile: the profile page in the app shows its YAML and its template.

  2. Put the template where the template: key points. The path is relative to the profile file, and it must stay inside .speccy/profiles/.

  3. Check the file:

    Terminal window
    speccy profile validate .speccy/profiles/sdd.yaml

    A valid file prints its key, its name and the number of checks. A file that is not valid prints each error with its path, and the command exits with code 2.

    A valid file can also print warnings. The command reads the docs of the profile in the folder, and the warnings use their headings. Run it in the folder with .speccy.yaml, or in a folder below it.

    • A rubric check that asks about one section, and has no section key, runs again on the whole doc after each edit. An edit to another section can then change its answer, and a review of the doc does not converge. The warning names the check and the heading. It says how many docs of the profile have that heading. When no doc has the heading, do not add that heading. Add section: none to keep the check on the whole doc, and the warning stops.
    • A rubric check whose section names a heading that no doc of the profile has reads the whole doc. The warning names the check and the heading. Change the section to a heading that the docs use.

    A profile from a release before 0.20.0 has no section keys, so read the warnings after an upgrade. The run report of a review shows the same warnings as notes, for the headings of the doc it reviewed.

    A rubric check whose question or pass_when names a doc type of links.upstream, such as “PRD”, and has no reads: [upstream] also gets a warning. Such a check cannot see that doc, so it fails on every doc. Compare a doc with its upstream doc shows the fix.

  4. Optional: look for checks that pull against each other:

    Terminal window
    speccy profile validate .speccy/profiles/sdd.yaml --conflicts

    The command sends the rubric checks to the model of the reviewer role, in one call. It prints each check, or pair of checks, whose pass conditions cannot both hold, with the reason. For example, one check allows a section to say “n/a”, and another check fails a section with no content. An author who fixes a finding of one such check gets a finding of the other, so a review of the doc does not converge. Change the pass condition of one of the two checks. The command changes nothing in the profile. Run it in a folder where Speccy has its models.

A running Speccy watches .speccy/profiles/, and it loads a changed file at once. A file that does not load shows as an error on the Profiles page, and Speccy keeps the last profiles that loaded.

The level decides what a failed check does. A MUST finding makes the doc Not Build Ready. A SHOULD finding counts in the score. An INFO finding is a hint.

For a check under checks:, change its level:

key: sdd
name: Software Design Document
template: templates/sdd.md
# The other keys and checks of the profile stay as they are.
checks:
- slug: sdd.observability
level: MUST
stage: rubric
scope: doc
section: Observability
sizes: [app, initiative]
question: Are logs, metrics, and alerts stated?
pass_when: Logs, metrics, and alerts are stated.

A lint rule is not under checks:. Change its level under lint.overrides. off turns the rule off:

key: sdd
name: Software Design Document
template: templates/sdd.md
lint:
overrides:
lint.passive-voice: { level: "off" }
lint.sentence-length: { level: INFO }
slop_extra: [going forward]
acronyms: [POL, STN, ADR]
# The other keys and checks of the profile stay as they are.
checks: []

slop_extra adds phrases to the list that lint.slop-phrase looks for.

acronyms names the acronyms that lint.undefined-acronym accepts with no definition. Use it for the words that every doc of your team uses, such as the labels of your document kinds.

The grounding stage reads the files of the bundle before it searches. When a file states the opposite of a claim in the doc, Speccy reports grounding.file-contradicts-claim at SHOULD. The doc can still be Build Ready.

To make that finding a MUST, set grounding.file_contradiction:

key: sdd
name: Software Design Document
template: templates/sdd.md
grounding:
file_contradiction: MUST
# The other keys and checks of the profile stay as they are.
checks: []

The value is SHOULD or MUST. With MUST, a doc that a file of its bundle contradicts is Not Build Ready until you correct the claim or the file. Use it when your team keeps the reference docs of a bundle correct.

Make a conflict block while the linked doc must change

Section titled “Make a conflict block while the linked doc must change”

An approved upstream request takes a conflict out of the verdict of the doc that asked. The conflict then waits on the linked doc. To keep the conflict blocking until the linked doc changes, set coherence.upstream_pending:

key: sdd
name: Software Design Document
template: templates/sdd.md
coherence:
upstream_pending: block
# The other keys and checks of the profile stay as they are.
checks: []

The value is allow or block. The default is allow. With block, the finding still reads “Waiting on” the linked doc, and the doc stays Not Build Ready. Upstream requests and send-backs explains the request.

A rubric check is one question that a model answers about the doc. It runs in a full review, not on each save.

key: sdd
name: Software Design Document
template: templates/sdd.md
# The other keys and checks of the profile stay as they are.
checks:
- slug: sdd.rollback
level: SHOULD
stage: rubric
section: Delivery
sizes: [app, initiative]
question: Does the doc say how to roll back each release step?
pass_when: Each release step has a named rollback, or the doc says it has none.
  • slug is lower case, with at least one dot, such as sdd.rollback. Each slug appears once in a profile.
  • stage is rubric, grounding, divergence or coherence.
  • section names the heading that the check is about. The check then reads only that section with its subsections, the doc title and the text assets. An edit to another section does not send the check to the model again. A waiver of the check ends when that section changes.
  • The check also reads each pointed-to section. That is a section of the same doc that the named section links to by its heading anchor. It can also be a section that the named section names by its full heading title. A title of one word counts only as a link. Thus a Security section that says “Governance and compliance records the deviation” can pass with the facts in Governance and compliance. Do not copy those facts into Security. An edit to a pointed-to section sends the check to the model again. You cannot list more sections in the profile. See the rubric stage.
  • The heading match is the match of lint.required-headings: case, spaces and a section number make no difference. When the doc has no such heading, the check reads the whole doc.
  • section is for a check of the rubric stage. Do not use it with scope: section.
  • scope is doc or section. With section, the check runs once for each section. The default is doc.
  • A rubric check with no section, and without scope: section, is a whole-doc check. The model judges it again after any edit, and a waiver of it does not end on an edit. Name a section when the check is about one section.
  • Write section: none on a whole-doc check that must read the whole doc, such as a check that compares two sections. The value none names no heading. profile validate and the run notes then give no warning about the section of the check.
  • sizes limits the check to the doc sizes you name. With no sizes, the check applies at every size.
  • question and pass_when are what the model reads. Write one binary question.

A failed rubric check reports every shortfall, and each shortfall is one finding. When the reviewer gives no valid answer for a MUST check after one more call, the check gets a MUST finding that says so. A waiver cannot cover that finding. Run the review again. A SHOULD or INFO check with no answer counts as not applicable. The built-in PRD and SDD profiles name a section on each check that is about one section of the template.

A rubric check reads the doc and the text assets of its bundle. It does not read a linked doc. To let a check compare the doc with its PRD, add reads: [upstream]:

key: sdd
name: Software Design Document
template: templates/sdd.md
links:
upstream: { kinds: [implements], types: [prd], required: true }
# The other keys and checks of the profile stay as they are.
checks:
- slug: sdd.context-delta
level: SHOULD
stage: rubric
section: Context
reads: [upstream]
question: Does the Context section add to the PRD and not repeat it?
pass_when: The Context section states what this design adds, and does not reprint the PRD.
  • The check also reads the spec doc of each implements or refines link target.
  • A change to the text of a target sends the check to the model again. An edit to the sidecar of the target does not.
  • When the doc links no such target, the model reads that the doc has no upstream doc.
  • reads is for a check of the rubric stage.

The built-in SDD check sdd.testing reads the PRD, because the MUST requirements are in the PRD.

A finding of your own check has no “What this check means” link, because the Check catalog lists only the built-in checks.

A waiver that people ask for again and again is a sign of a wrong limit. Change the limit, and stop approving the same waiver.

key: sdd
name: Software Design Document
template: templates/sdd.md
limits:
max_words: 8000
max_section_words: 1200
max_sentence_words: 25
max_code_block_lines: 40
max_table_rows: 15
# The other keys and checks of the profile stay as they are.
checks: []

lint.prose-limit, lint.sentence-length and lint.asset-nudge read these limits.

The template marks the headings that a doc must have. lint.required-headings reports a heading that is missing.

## Decisions <!-- required -->
## Data model <!-- required: app -->
  • <!-- required --> requires the heading at every size.
  • <!-- required: app --> requires it at app and initiative, and not at feature.

Mark a section that only large docs need in the template, not in the checks. Speccy removes the markers from a new doc that it writes from the template.

waivers names the policy for a SHOULD and for a MUST. A check can carry its own waiver, which wins over the policy of its level. The policy applies to Ship it open in hosted mode. In local mode, Ship it open closes at once. forbidden refuses Ship it open and Not needed in both modes.

key: sdd
name: Software Design Document
template: templates/sdd.md
waivers:
should: any_member
must: { n_approvals: 2 }
# The other keys and checks of the profile stay as they are.
checks:
- slug: sdd.security
level: MUST
stage: rubric
scope: doc
section: Security
sizes: [app, initiative]
waiver: forbidden
question: Are authentication, authorisation, secrets, and untrusted input addressed?
pass_when: Authentication, authorisation, secrets, and untrusted input are addressed.

Ask for and approve a waiver explains each policy.

  1. On the Profiles page, click New profile. Only an admin sees it.

  2. Enter a Key, such as rfc, and a Name.

  3. Under Start from, pick a profile to copy its YAML and its template. Pick Nothing: an empty profile to start with no checks.

  4. Click Create. The new profile opens, and you edit it as above.

A doc that names type: rfc in its frontmatter now uses the new profile. Delete on the profile page removes a profile that no bundle uses. A built-in profile cannot go.

Each save is a new version of the profile. A review run records the profile version it used, and an earlier review keeps that version. Speccy lints each doc of that type again with the new version. A rubric check that you add runs at the next full review.

  1. Open the profile, and go to Versions.

  2. Click an older version number. Speccy shows the diff of the YAML and of the template, from that version to the newest one.

  3. Click Roll back on the version you want.

A rollback writes a new version with the text of the version you picked. It reuses no number, so a version number always names the same text.