Trim redundant preambles in hand-authored agent docs#351
Merged
brianmhunt merged 5 commits intomainfrom Apr 21, 2026
Merged
Conversation
Same motivation as the generator-preamble strip in PR #349 — every agent that loads these docs on session start pays the cost of redundant metadata that the title and section 1 already carry. Applied to three hand-authored files: - `agents/soul.md`: collapsed the 4-line "This document describes the philosophical foundation..." preamble into a single sentence that keeps the AI-agent targeting and the "why not how" framing without the meta-commentary wrapper. - `agents/glossary.md`: removed the 1-line "Domain-specific terms..." preamble. Title + "Core Concepts" section already carry that signal. - `agents/options.md`: compressed the 3-sentence opener into one line that keeps the singleton name, file location, and scope ("two mechanisms for adding options"). Left untouched: - `agents/testing.md` — 137 lines of how-to with inline code; compression risks clarity for marginal byte savings. - `agents/contract.md` / `agents/guide.md` — preambles already minimal (1–3 lines of pointer prose). Adversarial pass: Explore subagent. Flagged 1 valid item — the initial soul.md tagline dropped the explicit AI-agent signal and broke tone parity with peer docs. Resolved by rewriting to a longer sentence that restores both. Also identified options.md as a follow-up candidate from the same pass; applied inline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 43 minutes and 23 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThese changes update documentation across multiple agent guides in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR trims redundant introductory preambles in three hand-authored agent-facing docs under tko.io/public/agents/, reducing repeated “what this doc is” meta-commentary while keeping the key “why/when to read” framing in place.
Changes:
- Condensed the intro paragraph in
soul.mdinto a single sentence. - Compressed the opener in
options.mdinto one line while keeping the file-location pointer. - Removed the one-line preamble from
glossary.mdso it starts directly at “Core Concepts”.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| tko.io/public/agents/soul.md | Collapses the multi-line preamble into a single intro sentence. |
| tko.io/public/agents/options.md | Compresses the ko.options intro while preserving location/scope info. |
| tko.io/public/agents/glossary.md | Removes redundant preamble so the glossary begins at core terms. |
| Read this to understand *why* the framework works the way it does, not just | ||
| *how* to use it. If you're an AI agent working on this codebase, this is | ||
| the context behind every design decision. | ||
| Read this to understand *why* TKO is shaped the way it is, not just *how* to use it. AI agents working on this codebase: this is the context behind every design decision. |
There was a problem hiding this comment.
The new intro line mentions only “TKO”, but the document title and early sections describe Knockout’s core model (and then TKO’s extensions). Consider referencing “Knockout/TKO” (or “Knockout’s model as implemented by TKO”) in the opener to better match the title and the content that follows.
Suggested change
| Read this to understand *why* TKO is shaped the way it is, not just *how* to use it. AI agents working on this codebase: this is the context behind every design decision. | |
| Read this to understand *why* Knockout/TKO is shaped the way it is, not just *how* to use it. AI agents working on this codebase: this is the context behind every design decision. |
Two more preamble/prose tightening candidates found in the
same pass as the previous commit:
- `agents/contract.md`: The meta-bullet under "## Replace X
With Y" ("This section is about replacing ad-hoc
DOM/event/state handling with bindings, not about binding-
syntax style.") was mixed into a list of actionable
replacement rules. Lifted out into a one-sentence lead-in
above the list so the bullets stay pure guidance.
- `agents/testing.md`: Trailing paragraph after the Option 1
example was three clauses that repeated what the example
already showed. Compressed to one line, kept the
`tko.js`-vendoring caveat intact.
Adversarial pass: Explore subagent. Flagged 3 items; 2 valid,
1 rejected:
- (valid) An earlier attempt to tighten the opener to
`Scope: ...` broke tonal parity with peer agent docs and
read as a metadata tag. Reverted to the original
"Use this file when..." phrasing.
- (valid) "unless vendored" alone was too generic in JS
ecosystem terms (could imply npm / bundled). Restored
"vendored locally" to preserve the specific workflow
(manual `tko.js` copy into the project).
- (rejected) Reviewer preferred the meta-bullet stay inside
the Replace X With Y list for "softer framing". Kept the
reorg — the meta-statement was a formatting bug in the
actionable bullet list, not an aside.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
testing.md + process.md instructed agents to query the
playground DOM by `#id` (e.g. `#preview`, `#console-messages`,
`#esbuild-status`, `#compile-time`, `#error-bar`). None of
those IDs exist. The playground uses `data-role` attribute
selectors throughout (`tko.io/src/playground/shell.ts`):
- `[data-role="preview"]` — iframe (line 54)
- `[data-role="console-messages"]` — console output container (line 61)
- `[data-role="status"]` — generic status element
shows "esbuild ready" label
(shell.ts:67 + runner-iife.ts:64)
- `[data-role="compile-time"]` — compile elapsed (line 68)
- `[data-role="error-bar"]` — hidden until a build error
(line 55)
Replaced every `#foo` playground reference in both files with
the correct attribute selector. The `#esbuild-status` →
`[data-role="status"]` mapping is worth calling out
specifically: the element is generic (handles loading → ready
→ error states), not esbuild-specific; the doc notes that the
label text becomes "esbuild ready" so an agent grepping the
snapshot still has the right string to look for.
Not a regression — these selector bugs pre-date this branch.
Found while reviewing testing.md for correctness after the
earlier preamble-strip pass; AGENTS.md had already migrated
its playwright flow to process.md in PR #349, so the fix had
a single home (no stale copy left behind).
Adversarial pass: Explore subagent cross-referenced every
selector against `tko.io/src/playground/shell.ts` +
`runner-iife.ts`. Result: clean, all five mappings match
actual DOM.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
tko.io/public/agents/options.md (1)
3-3: Consider clarifying the pronoun reference.The phrase "which to reach for" leaves "which" without a clear antecedent. Consider making it more explicit:
- "Two mechanisms for adding options — this page explains which mechanism to reach for."
- "Two mechanisms for adding options — this page explains when to use each."
The meaning is still clear from context, but directness helps readers (especially agents parsing the docs).
✍️ Optional phrasing alternatives
Option 1 (more explicit):
-`ko.options` is TKO's runtime configuration singleton, defined in `packages/utils/src/options.ts`. Two mechanisms for adding options — this page explains which to reach for. +`ko.options` is TKO's runtime configuration singleton, defined in `packages/utils/src/options.ts`. Two mechanisms for adding options — this page explains which mechanism to use.Option 2 (more direct):
-`ko.options` is TKO's runtime configuration singleton, defined in `packages/utils/src/options.ts`. Two mechanisms for adding options — this page explains which to reach for. +`ko.options` is TKO's runtime configuration singleton, defined in `packages/utils/src/options.ts`. Two mechanisms for adding options — this page explains when to use each.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tko.io/public/agents/options.md` at line 3, The sentence "Two mechanisms for adding options — this page explains which to reach for" uses an unclear pronoun; update the wording to explicitly reference what "which" refers to (e.g., "Two mechanisms for adding options — this page explains which mechanism to reach for" or "Two mechanisms for adding options — this page explains when to use each") in the document that describes ko.options (runtime config singleton defined in packages/utils/src/options.ts) so readers and agents clearly understand the intended choice between the two mechanisms.tko.io/public/agents/contract.md (1)
13-13: Effective compression with useful clarification.The compressed intro clearly states the section's purpose and includes a valuable negative clarification ("Not about binding-syntax style") that prevents confusion with the syntax preference discussion in lines 141-145.
Optional: Style refinement
The second sentence is a fragment. If you prefer more formal grammar:
-Replace ad-hoc DOM/event/state handling with bindings. Not about binding-syntax style. +Replace ad-hoc DOM/event/state handling with bindings. This is not about binding-syntax style.However, the current terse form aligns well with the PR's compression goal.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tko.io/public/agents/contract.md` at line 13, The intro currently reads "Replace ad-hoc DOM/event/state handling with bindings. Not about binding-syntax style."—make the second fragment a complete sentence for grammatical clarity by rephrasing the lines around the phrase "Not about binding-syntax style" (or combine them into one sentence such as keeping the clarified negative) while preserving the intended meaning and the existing emphasis on replacing ad-hoc DOM/event/state handling with bindings.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@tko.io/public/agents/contract.md`:
- Line 13: The intro currently reads "Replace ad-hoc DOM/event/state handling
with bindings. Not about binding-syntax style."—make the second fragment a
complete sentence for grammatical clarity by rephrasing the lines around the
phrase "Not about binding-syntax style" (or combine them into one sentence such
as keeping the clarified negative) while preserving the intended meaning and the
existing emphasis on replacing ad-hoc DOM/event/state handling with bindings.
In `@tko.io/public/agents/options.md`:
- Line 3: The sentence "Two mechanisms for adding options — this page explains
which to reach for" uses an unclear pronoun; update the wording to explicitly
reference what "which" refers to (e.g., "Two mechanisms for adding options —
this page explains which mechanism to reach for" or "Two mechanisms for adding
options — this page explains when to use each") in the document that describes
ko.options (runtime config singleton defined in packages/utils/src/options.ts)
so readers and agents clearly understand the intended choice between the two
mechanisms.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: dbf22fa9-9af9-4f01-a8c3-677d87a7c4a3
📒 Files selected for processing (6)
tko.io/public/agents/contract.mdtko.io/public/agents/glossary.mdtko.io/public/agents/options.mdtko.io/public/agents/process.mdtko.io/public/agents/soul.mdtko.io/public/agents/testing.md
💤 Files with no reviewable changes (1)
- tko.io/public/agents/glossary.md
Copilot review on PR #351 noted that the file title ("The Soul of Knockout") and early sections describe Knockout's core model before discussing TKO's extensions (the Provider Architecture section explicitly differentiates TKO from Knockout 3.x). The previous trimmed opener said "TKO is shaped the way it is" — understated the lineage. Changed to "Knockout/TKO is shaped the way it is" so the opener matches the file title + the model-first framing that follows. Adversarial pass: Copilot (external reviewer on PR #351). Flagged 1, valid, addressed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Claude Code drops local tooling artifacts under `.claude/` — `scheduled_tasks.lock` from `ScheduleWakeup`, `settings.local.json` from per-user settings, stray files from various subagent flows. Only `.claude/worktrees/` was previously ignored; the rest sat untracked-but-unignored, one accidental `git add .` away from landing on a branch. Broadened the pattern to `.claude/`. Verified: `git ls-files .claude/` returns empty, no historical commits have ever tracked anything under that directory (`git log --all -- .claude/` is empty), so no risk of masking existing tracked files. Fix prompted by finding `.claude/scheduled_tasks.lock` in the working tree after the earlier `ScheduleWakeup` call on this branch — a lockfile that "should not be possible" to leave around is now not possible. Adversarial pass: spot-verified inline — checked `git ls-files` + `git log --all` for any prior tracking of `.claude/` paths (none), confirmed the broadened pattern ignores every observable artefact (`scheduled_tasks.lock`, `settings.local.json`, stray `launch.json`, `worktrees/`). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
Follow-up to PR #349 — same preamble-strip motivation, applied to three hand-authored agent docs that carried meta-commentary the title + section 1 already communicated.
Left alone (explicit non-targets)
Savings
~400 bytes across the three files. Modest but deterministic, amortized on every agent session load.
Verification
🤖 Generated with Claude Code
Summary by CodeRabbit