Skip to content

docs: fix stale facts found in a docs accuracy audit - #80

Merged
ThomasK33 merged 1 commit into
mainfrom
docs/fix-stale-facts
Sep 23, 2026
Merged

docs: fix stale facts found in a docs accuracy audit#80
ThomasK33 merged 1 commit into
mainfrom
docs/fix-stale-facts

Conversation

@ThomasK33

@ThomasK33 ThomasK33 commented Sep 23, 2026

Copy link
Copy Markdown
Member

Fixes twelve places where user docs or package GoDoc disagreed with the code or with each other. No behavior changes; doc text and doc comments only.

Area Fix Evidence
docs/how-to/linear-agent-sessions.md Preemption is rejected for v0.x (ADR 0015), not "staged". docs/reference.md, ADR 0015
docs/tutorials/slack-bot.md Sample log line matches slog.Default() output; message.im is added in Step 6, not Step 2. examples/slack-hello-world/main.go:17,58
examples/slack-{redis,postgres,nats}-state/README.md Setup block says "From the repository root" (it runs cd examples/...). —
Slack example READMEs message.im marked optional in the event list, matching the scope table. —
Slack + Linear example READMEs List NATS JetStream with Redis/Postgres. examples/slack-nats-state
examples/linear-agent-hello-world/README.md Expected behavior now includes the action, external link, deploy select question, follow-up thought, and stop. main.go:146-185
adapters/slack/doc.go Retry wraps every Web API call and response_url post; multi-tenant bot user id should be treated as required. slack.go:683-694, interactive.go:499, docs/how-to/multi-tenant-install.md
adapters/linear/doc.go "Single-install by default", since multi-tenant mode exists. same file, multi-tenant section
docs/how-to/deferred-dispatch.md, docs/reference.md DetachTimeout is required under deferred dispatch; debounce needs DetachTimeout > DebounceInterval. runtime.go:356,384
docs/how-to/choose-a-state-backend.md REDIS_URL + redis.ParseURL, matching the example. examples/slack-redis-state/main.go:20
docs/linear-agent-capabilities.md, Linear how-to UpdateSession add/remove external URLs; drop redundant ReplacePlan: true from a non-empty plan snippet. adapters/linear/session.go:74-124

This is PR 1 of a docs cleanup. Next: README rewrite + contributor docs, then deduplicating the copied Slack setup sections.

Validation

  • go vet ./... and go test -count=1 ./... (root module) pass, including documentation_test.go (pinned phrases, README build, Linear snippet extraction).
  • The two edited unchecked snippets (Redis ParseURL, Linear UpdateSession) compile and vet in a scratch module with replace to this checkout.
  • Relative-link and anchor check over all user-facing Markdown: 0 broken.
  • gofmt -l adapters/ clean; git diff --check clean.

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

@ThomasK33
docs: fix stale facts found in a docs accuracy audit
dd7087f 
Correct twelve places where user docs or package GoDoc disagreed with the
code or with each other:

- Linear how-to: preemption is rejected for v0.x (ADR 0015), not staged.
- Tutorial: real slog.Default() log line; message.im is set up in Step 6.
- State example READMEs: the setup block runs from the repository root.
- Slack example READMEs: message.im is optional in the event list too.
- Example READMEs: list NATS JetStream alongside Redis and Postgres.
- Linear example README: expected behavior matches main.go (action,
  external link, `deploy` select question, follow-up thought, stop).
- Slack GoDoc: retry covers every Web API call and response_url post;
  the multi-tenant bot user id should be treated as required.
- Linear GoDoc: single-install by default, multi-tenant available.
- Deferred dispatch: DetachTimeout is required; debounce needs
  DetachTimeout > DebounceInterval.
- Backend how-to: REDIS_URL + ParseURL, matching the example.
- Linear capabilities: UpdateSession supports add/remove external URLs;
  the plan snippet no longer sets a redundant ReplacePlan.

_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `high`_
@ThomasK33 ThomasK33 mentioned this pull request Sep 23, 2026
Merged
@ThomasK33

ThomasK33 commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

ThomasK33 commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-23T15:00:18.074664Z dd7087f Manual request
🔒 Security Review ✅ Completed 2026-09-23T15:00:28.293324Z dd7087f Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: dd7087f2e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ThomasK33 ThomasK33 mentioned this pull request Sep 23, 2026
Merged
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: dd7087f2e0

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@ThomasK33 ThomasK33 mentioned this pull request Sep 23, 2026
Closed
@ThomasK33

ThomasK33 commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

Rendered-docs evidence (GitHub preview of the branch at dd7087f; documentation check only). The corrected preemption paragraph in the Linear how-to:

Linear how-to: no preemption

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

@ThomasK33

ThomasK33 commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

Readiness record: ready. Fixes 12 stale doc facts.

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

@ThomasK33
ThomasK33 merged commit 1bf7007 into main Sep 23, 2026
1 check passed
@ThomasK33
ThomasK33 deleted the docs/fix-stale-facts branch September 23, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ThomasK33