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.
Where the profiles live
Section titled “Where the profiles live”- Local mode. Speccy ships the
prdandsddprofiles 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.
Edit a profile in the app
Section titled “Edit a profile in the app”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.
-
Choose Profiles in the top bar, and click the profile.
-
Change the YAML in the left pane, or the template in the right pane. Help explains each key.
-
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.
Edit a profile as a file
Section titled “Edit a profile as a file”In local mode, you can also write the files yourself.
Directory.speccy/
Directoryprofiles/
- sdd.yaml
Directorytemplates/
- sdd.md
-
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. -
Put the template where the
template:key points. The path is relative to the profile file, and it must stay inside.speccy/profiles/. -
Check the file:
Terminal window speccy profile validate .speccy/profiles/sdd.yamlA 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
sectionkey, 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. Addsection: noneto keep the check on the whole doc, and the warning stops. - A rubric check whose
sectionnames a heading that no doc of the profile has reads the whole doc. The warning names the check and the heading. Change thesectionto a heading that the docs use.
A profile from a release before 0.20.0 has no
sectionkeys, 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
questionorpass_whennames a doc type oflinks.upstream, such as “PRD”, and has noreads: [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. - A rubric check that asks about one section, and has no
-
Optional: look for checks that pull against each other:
Terminal window speccy profile validate .speccy/profiles/sdd.yaml --conflictsThe command sends the rubric checks to the model of the
reviewerrole, 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.
Change a check’s level
Section titled “Change a check’s level”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: sddname: Software Design Documenttemplate: 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: sddname: Software Design Documenttemplate: templates/sdd.mdlint: 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.
Make a file contradiction block
Section titled “Make a file contradiction block”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: sddname: Software Design Documenttemplate: templates/sdd.mdgrounding: 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: sddname: Software Design Documenttemplate: templates/sdd.mdcoherence: 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.
Add a rubric check
Section titled “Add a rubric check”A rubric check is one question that a model answers about the doc. It runs in a full review, not on each save.
key: sddname: Software Design Documenttemplate: 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.slugis lower case, with at least one dot, such assdd.rollback. Each slug appears once in a profile.stageisrubric,grounding,divergenceorcoherence.sectionnames 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. sectionis for a check of the rubric stage. Do not use it withscope: section.scopeisdocorsection. Withsection, the check runs once for each section. The default isdoc.- A rubric check with no
section, and withoutscope: 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: noneon a whole-doc check that must read the whole doc, such as a check that compares two sections. The valuenonenames no heading.profile validateand the run notes then give no warning about the section of the check. sizeslimits the check to the doc sizes you name. With nosizes, the check applies at every size.questionandpass_whenare 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.
Compare a doc with its upstream doc
Section titled “Compare a doc with its upstream doc”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: sddname: Software Design Documenttemplate: templates/sdd.mdlinks: 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
implementsorrefineslink 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.
readsis 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.
Change the limits
Section titled “Change the limits”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: sddname: Software Design Documenttemplate: templates/sdd.mdlimits: 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.
Require a heading in the template
Section titled “Require a heading in the template”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 atappandinitiative, and not atfeature.
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.
Change who approves a waiver
Section titled “Change who approves a waiver”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: sddname: Software Design Documenttemplate: templates/sdd.mdwaivers: 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.
Make a new doc type
Section titled “Make a new doc type”-
On the Profiles page, click New profile. Only an admin sees it.
-
Enter a Key, such as
rfc, and a Name. -
Under Start from, pick a profile to copy its YAML and its template. Pick Nothing: an empty profile to start with no checks.
-
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.
What happens
Section titled “What happens”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.
Roll a profile back
Section titled “Roll a profile back”-
Open the profile, and go to Versions.
-
Click an older version number. Speccy shows the diff of the YAML and of the template, from that version to the newest one.
-
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.
Related
Section titled “Related”- Profile schema: every key and its values.
- Check catalog: every built-in check.
- Profiles and size: what size decides.
- Waivers and the sidecar.