docs: state public claims directly - #275
Conversation
Replace litotes and negative comparison framing across the active publication, public run labels, reader-facing examples, and frozen compatibility documentation. Keep factual absence states precise while moving recommendations and explanations into direct language. Make the preference durable in both agent instruction files, the public methodology, and the validation workflow. Verified with field-run and source validation, Astro type checking and production build, generated-route tests, Markdown lint, workflow YAML parsing, 45 cc tests, 175 lore tests, and the repository-wide litotes scan.
📝 WalkthroughWalkthroughThe change adds Markdown wording validation and updates repository guidance. It revises evidence, tooling, market, hardware, operating-system, field-lab, and run-page language to distinguish direct claims, pending work, unavailable measurements, and comparable evidence. ChangesDocumentation guidance and evidence
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 389d32ebe2
ℹ️ 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".
| `cc`, `lore`, and `time` are frozen through 2026-11-05. the compatibility window covers validated security issues, data-loss risks, current claude code compatibility breaks, and installation blockers. | ||
|
|
||
| the plugins remain available so existing users can migrate deliberately. they are not the active direction of the repository, and no codex ports are planned. | ||
| the plugins remain available so existing users can migrate deliberately. the active guide defines the repository's current direction, and the retirement plan excludes codex ports. |
There was a problem hiding this comment.
During the active compatibility window, this editorial rewrite and the similar changes under plugins/cc and plugins/lore fall outside the permitted security, data-loss, compatibility, and installation-blocker categories. Changing these frozen artifacts creates avoidable drift in the compatibility surface; keep the voice cleanup confined to the active handbook.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
| "https://github.com/anipotts/coding-agent-tips/tree/main/docs/decisions" | ||
| ], | ||
| "notes": "decisions were persisted in signed commits and repository documents; a separate resumed-session recovery was not run" | ||
| "notes": "decisions were persisted in signed commits and repository documents; resumed-session recovery remains pending" |
There was a problem hiding this comment.
The field-run policy in docs/field-lab/runs/README.md says records are immutable and corrections require a note or replacement run, but this rewrites the August 7 observation from “was not run” to “remains pending,” which adds a later claim about future work directly to the historical record. Preserve the original observation and publish any revised interpretation separately.
AGENTS.md reference: AGENTS.md:L21-L23
Useful? React with 👍 / 👎.
| const display = (value: string | number | null) => value ?? 'unavailable'; | ||
| const statusLabel = { complete: 'complete', partial: 'partially complete', pending: 'planned' }[run.status]; | ||
| const resultLabel = { pass: 'passed', fail: 'needs work', partial: 'partial', 'not-run': 'not run' }; | ||
| const resultLabel = { pass: 'passed', fail: 'needs work', partial: 'partial', 'not-run': 'pending' }; |
There was a problem hiding this comment.
In the current Codex baseline, delegated-analysis is not-run because delegation was outside the execution policy, while the run-level pending status is rendered as “planned.” Mapping every not-run scenario to “pending” therefore turns a deliberate omission into a future-work claim and collapses two distinct result states; retain a distinct reader-facing label for not-run.
AGENTS.md reference: AGENTS.md:L21-L23
Useful? React with 👍 / 👎.
|
|
||
| const { run } = Astro.props as { run: FieldRun }; | ||
| const display = (value: string | number | null) => value ?? 'not recorded'; | ||
| const display = (value: string | number | null) => value ?? 'unavailable'; |
There was a problem hiding this comment.
The shared formatter is used for fields whose null values have different meanings: in the current run, memoryGb is null because memory was not recorded, while the model identifier was unavailable from the product surface. Rendering both as “unavailable” contradicts the machine note and obscures whether data was inaccessible or simply unmeasured; use a neutral fallback or field-specific labels.
AGENTS.md reference: AGENTS.md:L7-L8
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
.github/workflows/validate.yml (1)
126-129: 🎯 Functional Correctness | 🔵 Trivial | 🏗️ Heavy liftAvoid scanning embedded examples as public prose.
The check scans every line in every tracked Markdown file. The repository’s
.markdownlint.jsoncLines 1-5 describe prompt-heavy content with embedded Markdown examples. A literal phrase in a fenced prompt or quoted source can therefore fail the workflow even when the public prose follows the rule. Restrict the scan to prose or add documented exceptions.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/validate.yml around lines 126 - 129, Update the litotes scan in the workflow so it does not flag matching phrases inside fenced examples or quoted prompt/source content, while continuing to validate public Markdown prose. Use the existing .markdownlint.jsonc guidance to define the excluded embedded-content patterns, or add narrowly documented exceptions without weakening checks for ordinary prose.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/validate.yml:
- Around line 126-129: Update the git grep check in the validation workflow to
capture its exit status and accept only status 1 as “no match”; continue failing
on status 0 for matches and propagate any other nonzero status as a scan error.
Keep the existing message and exit behavior for detected matches.
In `@docs/claude-code/README.md`:
- Line 29: Update the local installation note in the README by adding its
observation date and environment, or remove the environment-specific “2.1.220 is
installed” statement from the public page. Keep the hands-on protocol status as
a separate statement.
In `@docs/market/hardware.md`:
- Line 33: Update the hosted inference statement in the hardware documentation
to avoid implying that repository work is always local. Scope it specifically to
hosted models using local agents, or explicitly describe both local-agent and
remote-agent execution patterns while preserving the distinction defined by the
hosted-model terminology nearby.
In `@docs/shared/operating-system.md`:
- Line 107: Revise the sentence around the agent infrastructure workflow
comparison to qualify “outperform” by stating the conditions or evidence
supporting that outcome, or explicitly framing it as an inference. Preserve the
recommendation while clearly distinguishing evidence-based observations from
inference.
- Line 60: Update the Git isolation guidance in the operating-system
documentation to clarify that worktrees isolate checked-out tracked files and
branch selection, while branch references, repository objects, remotes, and
other Git metadata remain shared. Preserve the existing warning about shared
runtime resources and parallel implementations.
In `@src/pages/field-lab/runs/`[runId].astro:
- Line 40: Update the display helper to return “unavailable” for empty optional
strings as well as nullish values, while preserving non-empty strings and
numbers; use the existing display symbol in
src/pages/field-lab/runs/[runId].astro rather than changing unrelated schema
definitions.
---
Nitpick comments:
In @.github/workflows/validate.yml:
- Around line 126-129: Update the litotes scan in the workflow so it does not
flag matching phrases inside fenced examples or quoted prompt/source content,
while continuing to validate public Markdown prose. Use the existing
.markdownlint.jsonc guidance to define the excluded embedded-content patterns,
or add narrowly documented exceptions without weakening checks for ordinary
prose.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 16fa3515-04de-49e9-b332-9524f816001d
📒 Files selected for processing (20)
.github/workflows/validate.ymlAGENTS.mdCLAUDE.mddocs/claude-code/README.mddocs/codex/README.mddocs/field-lab/README.mddocs/field-lab/runs/README.mddocs/field-lab/runs/codex-publication-baseline-2026-08-07.jsondocs/legacy-tools.mddocs/market/README.mddocs/market/hardware.mddocs/methodology.mddocs/shared/operating-system.mdexamples/agents/try-worktree.mdexamples/agents/write-pr.mdplugins/README.mdplugins/cc/README.mdplugins/cc/eval/README.mdplugins/lore/README.mdsrc/pages/field-lab/runs/[runId].astro
| if git grep -n -iE '\bnot (only|just|merely|simply|uncommon|insignificant|impossible|bad|wrong|unreasonable|unlikely|automatically|enough)\b|\bno (small|minor|mean|little)\b' -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)plugins/**/CHANGELOG.md'; then | ||
| echo "litotes or negative comparison framing found" | ||
| exit 1 | ||
| fi |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Propagate git grep errors.
Line 126 runs git grep as the if condition. A match returns 0, and no match returns 1. A scan error can return another nonzero status. Because the condition has no else branch, a scan error can make this validation step pass. Accept only status 1 as “no match” and propagate every other error.
Suggested status handling
if git grep -n -iE '\bnot (only|just|merely|simply|uncommon|insignificant|impossible|bad|wrong|unreasonable|unlikely|automatically|enough)\b|\bno (small|minor|mean|little)\b' -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)plugins/**/CHANGELOG.md'; then
echo "litotes or negative comparison framing found"
exit 1
+ else
+ status=$?
+ if [ "$status" -ne 1 ]; then
+ echo "Markdown scan failed"
+ exit "$status"
+ fi
fi📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| if git grep -n -iE '\bnot (only|just|merely|simply|uncommon|insignificant|impossible|bad|wrong|unreasonable|unlikely|automatically|enough)\b|\bno (small|minor|mean|little)\b' -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)plugins/**/CHANGELOG.md'; then | |
| echo "litotes or negative comparison framing found" | |
| exit 1 | |
| fi | |
| if git grep -n -iE '\bnot (only|just|merely|simply|uncommon|insignificant|impossible|bad|wrong|unreasonable|unlikely|automatically|enough)\b|\bno (small|minor|mean|little)\b' -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)plugins/**/CHANGELOG.md'; then | |
| echo "litotes or negative comparison framing found" | |
| exit 1 | |
| else | |
| status=$? | |
| if [ "$status" -ne 1 ]; then | |
| echo "Markdown scan failed" | |
| exit "$status" | |
| fi | |
| fi |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/validate.yml around lines 126 - 129, Update the git grep
check in the validation workflow to capture its exit status and accept only
status 1 as “no match”; continue failing on status 0 for matches and propagate
any other nonzero status as a scan error. Keep the existing message and exit
behavior for detected matches.
| primary source: [official claude code documentation](https://code.claude.com/docs/en) | ||
|
|
||
| local note: 2.1.220 is installed, but the current hands-on protocol in [methodology](/method/) has not been rerun for this reset. recommendations below that depend on current product behavior are therefore source-verified rather than presented as fresh comparative testing. | ||
| local note: 2.1.220 is installed. the current hands-on protocol in [methodology](/method/) remains pending for this reset, so recommendations that depend on current product behavior use source-verified evidence. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file context =="
sed -n '1,45p' docs/claude-code/README.md
echo "== related local note occurrences =="
rg -n "2\.1\.220|installed|source-verified|hands-on protocol|pending" docs/claude-code/README.mdRepository: anipotts/coding-agent-tips
Length of output: 3025
Scope the local installation note.
2.1.220 is installed is environment-specific. Add the observation date and environment, or remove it from the public page. Keep the hands-on protocol status as a separate supported statement.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/claude-code/README.md` at line 29, Update the local installation note in
the README by adding its observation date and environment, or remove the
environment-specific “2.1.220 is installed” statement from the public page. Keep
the hands-on protocol status as a separate statement.
Source: Coding guidelines
| | hosted model, many local agents | provider | your machine | duplicated workspaces and simultaneous development processes | | ||
|
|
||
| using a hosted model does not make the workflow resource-free. it removes model inference from the mac while leaving the repository workload local. | ||
| hosted inference moves model compute away from the mac while repository work remains local. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Scope the hosted-inference statement.
At Line 33, the statement says repository work remains local for hosted inference. Line 29 defines a hosted-model, remote-agent pattern where code execution is remote. Apply this statement only to hosted models with local agents, or describe both execution patterns.
Proposed wording
-hosted inference moves model compute away from the mac while repository work remains local.
+when the agent runs locally, hosted inference moves model compute away from the mac while repository work remains local.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| hosted inference moves model compute away from the mac while repository work remains local. | |
| when the agent runs locally, hosted inference moves model compute away from the mac while repository work remains local. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/market/hardware.md` at line 33, Update the hosted inference statement in
the hardware documentation to avoid implying that repository work is always
local. Scope it specifically to hosted models using local agents, or explicitly
describe both local-agent and remote-agent execution patterns while preserving
the distinction defined by the hosted-model terminology nearby.
| use one branch or worktree per independently reviewable change. parallel agents need explicit ownership of files, subsystems, or responsibilities. | ||
|
|
||
| git isolation does not isolate runtime resources. check ports, databases, local services, browser profiles, caches, generated files, and external accounts before running several implementations at once. | ||
| git isolation covers tracked files and branches. runtime resources remain shared, so check ports, databases, local services, browser profiles, caches, generated files, and external accounts before running several implementations at once. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Clarify the scope of Git isolation.
At Line 60, worktrees isolate checked-out tracked files and branch selection. Branch references, repository objects, remotes, and other Git metadata remain shared. State this boundary so parallel agents do not treat branch updates as fully isolated.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/shared/operating-system.md` at line 60, Update the Git isolation
guidance in the operating-system documentation to clarify that worktrees isolate
checked-out tracked files and branch selection, while branch references,
repository objects, remotes, and other Git metadata remain shared. Preserve the
existing warning about shared runtime resources and parallel implementations.
| - whether the change is easier to understand than the system it replaces. | ||
|
|
||
| the same standard applies to agent infrastructure. a large control plane is not automatically more capable than a small, well-understood workflow. | ||
| the same standard applies to agent infrastructure. a small, well-understood workflow can outperform a large control plane. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Qualify the outperform claim.
Line 107 presents a comparative outcome without stating its conditions or evidence. State the conditions that support the claim, or label it as an inference.
As per coding guidelines, public documentation must separate observed behavior, official product facts, and inference. Based on learnings, recommendations must follow from the evidence and prose must preserve precision.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/shared/operating-system.md` at line 107, Revise the sentence around the
agent infrastructure workflow comparison to qualify “outperform” by stating the
conditions or evidence supporting that outcome, or explicitly framing it as an
inference. Preserve the recommendation while clearly distinguishing
evidence-based observations from inference.
Sources: Coding guidelines, Learnings
|
|
||
| const { run } = Astro.props as { run: FieldRun }; | ||
| const display = (value: string | number | null) => value ?? 'not recorded'; | ||
| const display = (value: string | number | null) => value ?? 'unavailable'; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Handle empty optional strings as unavailable.
At Line 40, display replaces only nullish values. The schema permits empty strings for productVersion, model, and machineProfile.notes. Those values render as blank fields instead of unavailable. Reject empty strings in the schema or normalize them here.
Proposed fix
-const display = (value: string | number | null) => value ?? 'unavailable';
+const display = (value: string | number | null) =>
+ typeof value === 'string' && value.trim() === '' ? 'unavailable' : value ?? 'unavailable';📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const display = (value: string | number | null) => value ?? 'unavailable'; | |
| const display = (value: string | number | null) => | |
| typeof value === 'string' && value.trim() === '' ? 'unavailable' : value ?? 'unavailable'; |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/field-lab/runs/`[runId].astro at line 40, Update the display helper
to return “unavailable” for empty optional strings as well as nullish values,
while preserving non-empty strings and numbers; use the existing display symbol
in src/pages/field-lab/runs/[runId].astro rather than changing unrelated schema
definitions.
1 participant
why
the launch copy still used litotes and negative comparison frames in several guides, evidence labels, run notes, and compatibility pages. direct claims make the reasoning easier to scan and easier to defend.
changes
verification
boundaries
historical changelogs retain their original wording. direct safety prohibitions and factual pending or unavailable states remain precise.
Summary by CodeRabbit
Documentation
Style
Quality