docs: scaffold docs/.style for the prose style guide#25466
Merged
nickvigilante merged 4 commits intoJun 17, 2026
Merged
Conversation
Docs preview📖 View docs preview for |
Contributor
Author
|
/coder-agents-review Focus areas (in order):
Filed via Coder Agents on Nick's behalf. |
Contributor
There was a problem hiding this comment.
Clean, well-documented scaffold. The layered exclusion strategy (manifest primary, trigger filter secondary, pathspec tertiary) is properly reasoned and each layer is documented. The pre-mortem covering first-push-to-new-branch and workflow-dispatch edge cases is the kind of analysis that prevents 2 AM debugging. The real README in styles/Coder/ instead of .gitkeep is a good call.
1 P2, 3 P3, 2 Nits, 3 Notes. The P2 and one P3 share a root cause: the blockquote and AGENTS.md bullet prematurely delegate prose authority to an empty scaffold while mischaracterizing the file that actually has the rules. The fix is a transitional note, not a structural change. One P3 is a missing path negation in docs-preview.yaml (this PR's own preview comment demonstrates the 404). One P3 notes the scaffold lacks a cross-reference to the existing deployed guide.
"An agent editing
docs/today reads this bullet, follows the link, gets five 'to be filled in' placeholders, and comes back empty-handed." (Leorio)
🤖 This review was automatically generated with Coder Agents.
nickvigilante
added a commit
that referenced
this pull request
May 18, 2026
Five small fixes from coder-agents-review on PR #25466: - DEREM-2 (P2): The blockquote in .claude/docs/DOCS_STYLE_GUIDE.md pointed readers to a scaffold and away from the Writing Style section on the same file. Reframe to a transitional note: keep using the Writing Style section below until the prose guide is populated. - DEREM-3 + DEREM-6 + DEREM-7: Apply the same transitional framing in the AGENTS.md bullet, replace the ephemeral 'new style guide' with 'prose style guide', and drop the misleading 'repo-root' qualifier on .claude/docs/. - DEREM-4: Add 'docs/.style/**' negation to .github/workflows/ docs-preview.yaml's path filter, and have the first-doc selection skip .style/ when picking the preview target on mixed PRs. Folds DOCS-184 into this PR. - DEREM-5: Add a Relationship section to docs/.style/style-guide.md that names docs/about/contributing/documentation.md as the public summary pending the IA rework redirect. - DEREM-8: List deploy-docs and docs-preview in the README's 'What does not run against this directory' section now that both are configured to skip .style. Refs DOCS-180.
Contributor
Author
|
Thanks for the review. Resolutions in Acted on
Noted only
Filed via Coder Agents on Nick's behalf. |
Contributor
Author
|
/coder-agents-review |
Contributor
There was a problem hiding this comment.
All R1 findings verified fixed or acknowledged. The P2 blockquote mischaracterization, the docs-preview.yaml gap, the missing cross-reference, the AGENTS.md wording, all cleanly resolved in 7e43962. Hisoka traced the docs-preview.yaml fix through every edge case (mixed PRs, race conditions) and confirmed defense in depth holds at every layer.
Two P4s remain, neither blocking.
DEREM-5's redirect ticket half needs a human decision. The author noted the IA rework is in flight under DOCS-93 but the specific redirect has no dedicated ticket. The text says "An information-architecture rework will redirect that page to this guide" with no link. Every other future-work reference in these files (29 of them) points to a specific Linear ticket. This one alone doesn't. Filing a ticket or explicitly accepting the gap is a call for Nick.
The third-party references table duplication between style-guide.md and documentation.md is real and acknowledged; author will deduplicate when the redirect lands.
"The person debugging a deploy at 2 AM reads these comments and understands the full picture without opening a second file." (Leorio, on the workflow comments)
🤖 This review was automatically generated with Coder Agents.
Contributor
Author
|
Status check, ready for human review. The bot panel approved at R2 (commit 7e43962). Two non-blocking P4 follow-ups raised in that approval are now addressed on top:
Follow-ups landed in 960e4f7. Subsequent commit e8fb18c is a small post-approval cleanup (removed leftover Linear-URL references inside the scaffold prose, since the scaffold is meant to be repo-internal). CI is green. Looping for human review when convenient. Generated by Coder Agents on behalf of @nickvigilante. |
nickvigilante
added a commit
that referenced
this pull request
Jun 10, 2026
Five small fixes from coder-agents-review on PR #25466: - DEREM-2 (P2): The blockquote in .claude/docs/DOCS_STYLE_GUIDE.md pointed readers to a scaffold and away from the Writing Style section on the same file. Reframe to a transitional note: keep using the Writing Style section below until the prose guide is populated. - DEREM-3 + DEREM-6 + DEREM-7: Apply the same transitional framing in the AGENTS.md bullet, replace the ephemeral 'new style guide' with 'prose style guide', and drop the misleading 'repo-root' qualifier on .claude/docs/. - DEREM-4: Add 'docs/.style/**' negation to .github/workflows/ docs-preview.yaml's path filter, and have the first-doc selection skip .style/ when picking the preview target on mixed PRs. Folds DOCS-184 into this PR. - DEREM-5: Add a Relationship section to docs/.style/style-guide.md that names docs/about/contributing/documentation.md as the public summary pending the IA rework redirect. - DEREM-8: List deploy-docs and docs-preview in the README's 'What does not run against this directory' section now that both are configured to skip .style. Refs DOCS-180.
e8fb18c to
14eca1f
Compare
Contributor
Author
|
@tracyjohnsonux @DevelopmentCats Can I get your review on this PR when you get a chance? |
nickvigilante
added a commit
that referenced
this pull request
Jun 16, 2026
Five small fixes from coder-agents-review on PR #25466: - DEREM-2 (P2): The blockquote in .claude/docs/DOCS_STYLE_GUIDE.md pointed readers to a scaffold and away from the Writing Style section on the same file. Reframe to a transitional note: keep using the Writing Style section below until the prose guide is populated. - DEREM-3 + DEREM-6 + DEREM-7: Apply the same transitional framing in the AGENTS.md bullet, replace the ephemeral 'new style guide' with 'prose style guide', and drop the misleading 'repo-root' qualifier on .claude/docs/. - DEREM-4: Add 'docs/.style/**' negation to .github/workflows/ docs-preview.yaml's path filter, and have the first-doc selection skip .style/ when picking the preview target on mixed PRs. Folds DOCS-184 into this PR. - DEREM-5: Add a Relationship section to docs/.style/style-guide.md that names docs/about/contributing/documentation.md as the public summary pending the IA rework redirect. - DEREM-8: List deploy-docs and docs-preview in the README's 'What does not run against this directory' section now that both are configured to skip .style. Refs DOCS-180.
14eca1f to
c184080
Compare
Adds a private contributor-tooling directory at docs/.style/ that holds: - README.md explaining the convention and the no-deploy guarantee - style-guide.md as a scaffold for the canonical prose style guide - styles/Coder/ as the home for custom Vale rules (filled by follow-ups) Defense-in-depth tweaks to .github/workflows/deploy-docs.yaml exclude docs/.style/** from the push trigger and from the surgical-reindex git diff. coder.com/docs route discovery is already manifest-driven, so nothing under docs/.style/ becomes a route or an Algolia record. Also: - .github/.linkspector.yml: skip external-link checks under docs/.style/ - AGENTS.md: point agents at the new style guide - .claude/docs/DOCS_STYLE_GUIDE.md: cross-link to the canonical prose guide; this file remains the structure/research companion The Vale configuration that consumes docs/.style/styles/ lands in a follow-up PR (DOCS-40). Closes DOCS-180.
Five small fixes from coder-agents-review on PR #25466: - DEREM-2 (P2): The blockquote in .claude/docs/DOCS_STYLE_GUIDE.md pointed readers to a scaffold and away from the Writing Style section on the same file. Reframe to a transitional note: keep using the Writing Style section below until the prose guide is populated. - DEREM-3 + DEREM-6 + DEREM-7: Apply the same transitional framing in the AGENTS.md bullet, replace the ephemeral 'new style guide' with 'prose style guide', and drop the misleading 'repo-root' qualifier on .claude/docs/. - DEREM-4: Add 'docs/.style/**' negation to .github/workflows/ docs-preview.yaml's path filter, and have the first-doc selection skip .style/ when picking the preview target on mixed PRs. Folds DOCS-184 into this PR. - DEREM-5: Add a Relationship section to docs/.style/style-guide.md that names docs/about/contributing/documentation.md as the public summary pending the IA rework redirect. - DEREM-8: List deploy-docs and docs-preview in the README's 'What does not run against this directory' section now that both are configured to skip .style. Refs DOCS-180.
Two prose-only edits on top of the bot's approval at review id 4320487709, both flagged as non-blocking P4s. DEREM-10: the IA-rework redirect now references DOCS-186 explicitly, matching the per-ticket convention used by the other 29 future-work references in the new files. DEREM-11: the "How to use this guide" section opens with a one-sentence scaffold acknowledgment that points direct visitors at the public summary at docs/about/contributing/documentation.md, so a contributor who lands here without first reading AGENTS.md does not hit empty sections and bounce. Verification: make fmt/markdown, make lint/markdown, make lint/emdash all clean.
Strip Linear ticket links, the Linear project link, and the Linear
references from the prose so the PR reviews cleanly for people who
don't have access to (or don't care about) Linear. Mention follow-up
PRs in plain language where the previous version pointed at specific
tickets.
- docs/.style/README.md: drop the DOCS-40 link from the Vale
bullet; rewrite the 'Editing the style guide' section without
the project link.
- docs/.style/style-guide.md: rewrite the status note and 'How to
use this guide' lead-in without 'Linear tickets' wording; drop
ticket links from every 'Planned coverage' bullet (Voice and
tone, Word choice, Capitalization and punctuation, Formatting);
drop DOCS-40/-178/-186 links from Vale enforcement, Editor
setup, and the public-summary section; change the third-party
references table separator from ' - ' to a comma to avoid the
repo's ' -- '-style punctuation lint pattern.
- docs/.style/styles/Coder/README.md: replace the ticket roadmap
table with a bullet list of planned rules; drop the
DOCS-179-tracked parity CI check reference.
No behavior change; this is documentation-only and the structural
content (sections, headings, planned scope) is preserved.
c184080 to
3e26bed
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a private contributor-tooling directory at
docs/.style/that will host the canonical prose style guide and the custom Vale rules used to enforce it. The directory's contents do not deploy tocoder.com/docs.This PR is the scaffold only. The Vale configuration, the rule set, and the per-rule style-guide sections all land in follow-up PRs.
What changes
docs/.style/directory with:README.mdexplaining the conventionstyle-guide.mdas a table-of-contents scaffoldstyles/Coder/README.mdplaceholder so Git tracks the empty Vale rules dir.github/workflows/deploy-docs.yaml: skip the workflow on.style-only pushes, and exclude.stylepaths from the surgical-reindex git diff on mixed commits. Defense-in-depth on top of the manifest-driven coder.com routing..github/.linkspector.yml: adddocs/.styletoexcludedDirsAGENTS.mdand.claude/docs/DOCS_STYLE_GUIDE.md: cross-link to the new style guide for agentsVerification
make pre-commit-lightclean (fmt/markdown,lint/markdown,lint/typos,lint/emdash,lint/actions/actionlint,lint/shellcheck).markdown-table-formatter --checkandmarkdownlint-cli2both process the new files (existing globs arefind docs -name '*.md').actionlintclean on the modified workflow.docs/manifest.json. The workflow changes are defense in depth.Implementation plan and decision log
Decisions
docs/.style/(leading dot, mirrors.github/,.vscode/,.claude/). Vale'sStylesPathwill bedocs/.style/styles/;.vale.inilands at repo root in a follow-up.docs/about/contributing/documentation.md: untouched in this PR. Nick's separate information-architecture rework will redirect it to GitHub at the right time.styles/Coder/: realREADME.md, not.gitkeep. Discoverable on GitHub, lints with the existing tooling, lists the planned starter rules.coder.com/docs/CONTRIBUTING; bloating it would defeat the redirect..claude/docs/DOCS_STYLE_GUIDE.md: kept as the structure/research companion. A blockquote at the top points at the new canonical prose guide.coder.com exclusion mechanism (verified by inspection)
Direct inspection of
coder/coder.com:src/utils/docs/docs.tsiteratesroutesfromdocs/manifest.json. Files not in the manifest never become routes.src/utils/algoliaDocs/surgical.tsexplicitly skips paths not in the manifest, incrementingpathsSkipped.Net result: not adding anything from
docs/.style/tomanifest.jsonis the only thing that has to be true for the exclusion to work. Thedeploy-docs.yamltweaks are defense in depth.deploy-docs.yaml changes (pre-mortem)
!docs/.style/**skips the workflow on.style-only pushes. GitHub Actions only suppresses when every changed file matches a negation, so mixed commits still trigger.:(exclude)docs/.style/**drops.stylepaths from the surgical-reindex payload on mixed commits.Risks considered:
.github/workflows/test-deploy-docs-diff.shonly exercises the downstream awk parser, not the git-diff invocation. The exclusion happens at git-diff time; the parser sees the same<status>\0<path>\0format. No test change needed.BEFORE_SHAis all zeros. Whole-branch reindex re-extracts records from the manifest, which still excludes.stylefiles because they are not in the manifest.Why a real README in
styles/Coder/instead of.gitkeepIt explains intent, lists the upcoming rules, and lints with the existing tooling. The cost is one extra Markdown file; the upside is that a contributor browsing GitHub sees the plan without clicking around.
Filed via Coder Agents on Nick's behalf.
Linear: DOCS-180