Skip to content

docs: add decisions under docs/adr/ and sign in right after install - #948

Merged
austinborn merged 2 commits into
mainfrom
docs/readme-decisions-and-sign-in-order
Nov 18, 2026
Merged

austinborn merged 2 commits into
mainfrom
docs/readme-decisions-and-sign-in-order

Conversation

@austinborn

Copy link
Copy Markdown
Contributor

Summary

The README and Getting Started now send people to docs/adr/ for their architecture decisions, through the two paths that also write the rule file the checks read: actual adr new from their own terminal, or the pull request app.actual.ai opens. The hand-written rule-file example comes out: a decision typed into docs/adr/ by hand has no rule file, so it's never checked. .actual/rules/ now shows up only where the docs say what the checks read.

Optional sign-in moves to the step right after installing the plugin and the CLI, in both files. actual.ai/cli/docs is now a short quick start, so the README drops its "Command reference" link and How It Works points at Getting Started's command list. A changelog bullet under Unreleased records the change.

actual adr new first shipped in 0.14.0, which is out on GitHub, npm and Homebrew, so nothing holds the merge. It's Markdown only, so the risk is low. The README paragraph on the actual adr commands stays byte-identical because #943 rewrites it (this branch merges cleanly with #943). Once both land, that paragraph's first clause repeats the new step, and it'd be worth trimming then.

Test plan and supporting detail

Test plan

Not exercised

The sync pull request from app.actual.ai writes the same two files for each accepted decision, as docs/ADR_COMMANDS.md describes; that path wasn't run for this change.


Generated by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-1m3hdz
• On behalf of: @austinborn

austinborn and others added 2 commits November 17, 2026 11:57
The README and Getting Started send new decisions to docs/adr/ through
`actual adr new` or the pull request app.actual.ai opens, both of which
write the rule file the checks read beside the decision. The
hand-written rule-file example goes, since a decision typed into
docs/adr/ by hand has no rule file and is never checked. Optional
sign-in moves to the step right after installation.

actual.ai/cli/docs is now a short quick start rather than a command
reference, so the README and How It Works point at this repository's
docs for the commands.

City: city · Agent: local-core__builder-ci-wisp-1m3hdz
@austinborn
austinborn enabled auto-merge November 18, 2026 15:07

@benw5483 benw5483 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: the original rule-file format is no longer documented anywhere

Changed code: README.md:51-61 (the section that replaces the ### Rules example)

Evidence: The README example was the only place that showed a rule file's body: a title, a sentence on where the rules apply, and a ### Rules list of **ID** LEVEL: statement lines. The CLI still reads that format with or without a v2 header. A hand-written file in exactly the removed shape, dropped into .actual/rules/ on 0.14.0, lists in actual rules ls as api-error-handling: MUST 1 · MUST_NOT 1 and is enforced. The docs still point at the format without defining it: HOW_IT_WORKS.md:83 says "files without one work as before", line 109 says "or the original format", and docs/SCOPE_INDEX.md:76 says the same. docs/ADR_COMMANDS.md names a "### Rules list with one rule per policy" but not the line syntax.

Impact: Teams that already keep hand-written rule files (the README's documented path until this PR) lose their only reference for the ID and level syntax. Someone editing a synced rule file by hand has nothing to check it against either. The PR's reasoning holds for decisions: a file typed into docs/adr/ by hand has no rule file and is never checked. It doesn't cover rule files written directly.

Fix: Keep the example, moved out of the quick start. One option is a collapsed "Writing a rule file by hand" block under Governance in HOW_IT_WORKS, which line 83 can then link to.

P3: the new step doesn't say to run actual adr new from the repository root

Changed code: README.md:53, docs/GETTING_STARTED.md:131

Evidence: adr new writes relative to the current directory (--root defaults to it, as docs/ADR_COMMANDS.md:42 says). Running the README's command from src/ with 0.14.0 at a terminal wrote src/docs/adr/<id>-use-grpc-internally.md and src/.actual/rules/cross-cutting-use-grpc-internally-<hash>.md, then printed "It is accepted, so plan-check and impl-check enforce it now." actual rules ls at the repository root doesn't list that rule.

Impact: This PR makes adr new the first way the docs offer to add a decision, and the text says it writes the decision "there", meaning docs/adr/. Someone whose shell is in a subdirectory gets a decision that is never checked from the root, along with a message saying it's enforced.

Fix: Add "from your repository root" to both sentences, or mention --root. The misleading success message is CLI behaviour and out of scope here.

@austinborn
austinborn added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit 9283864 Nov 18, 2026
10 checks passed
@austinborn
austinborn deleted the docs/readme-decisions-and-sign-in-order branch November 18, 2026 16:03

@backlineint backlineint left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intent is clear, and the README and Getting Started changes match docs/ADR_COMMANDS.md. Two things to fix and one to track.

1. Duplicate ### Changed heading in Unreleased (CHANGELOG.md, ~line 19)
Unreleased already has a ### Changed section with two bullets, and this PR adds a second ### Changed heading below it. Keep a Changelog expects one heading per type per release. Please append the new bullet to the existing section.

2. The draft caveat doesn't say how to make a draft accepted (README.md and docs/GETTING_STARTED.md, "Adding decisions")
Both say a draft written from an agent's shell is read by no check "until its status is accepted", but neither says how to make it accepted. Someone running this from an agent shell ends up with a rule that never fires and no pointer to the fix. Please name the step, such as --status accepted at creation or editing the status in the file's header, whichever is correct.

3. Follow-up for the repeated README sentence (README.md, paragraph after "Adding decisions")
That paragraph opens with "actual adr new writes a decision and its rule file from the terminal…", which now repeats the new section. The PR description defers this until #943 lands. Please track it, for example with a follow-up issue, so it isn't forgotten.

@austinborn

Copy link
Copy Markdown
Contributor Author

Follow-up to this review: #954 makes the first two changes. Unreleased keeps one ### Changed heading. The README and Getting Started now say how to accept a draft: change status: draft to status: accepted in both files' headers and Status: proposed to Status: accepted in the decision file, or have the agent pass --status accepted so it writes an accepted decision in the first place.

The third point, the repeated actual adr new sentence, waits on #943, which rewrites that paragraph. It's tracked for a trim once #943 merges.


Posted by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-r28ve8
• On behalf of: @austinborn

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants