Agent guides: add the mechanical-simple-auditable design law - #2339
Merged
Conversation
Add the design law to 01-rules.md with a worked example anonymised as 'an agent', link it from index.md, and rebuild the compiled manual. Trim verbose prose in the image-prompting guide to stay within the compiled manual 18000-char budget. Update CHANGELOG.
|
ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing |
📝 WalkthroughWalkthroughThe change adds design-law guidance to the agent manual and compiled manual. It also shortens image-prompting guidance while retaining core prompt, parameter, model-selection, and iteration recommendations. The changelog records both documentation updates. ChangesAgent manual documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
CHANGELOG.md (1)
12-15: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winAdd an automated check for the compiled-manual budget.
The changelog records an 18,000-character constraint, but this diff adds no test or documentation check. Add CI validation that compares generated output with
docs/taos-agent-manual.mdand enforces the stated budget.🤖 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 `@CHANGELOG.md` around lines 12 - 15, Add CI validation for the generated agent manual, comparing the generated output against docs/taos-agent-manual.md and failing when the compiled content exceeds the documented 18,000-character budget. Anchor the check to the existing manual generation command or workflow configuration, and ensure it detects both stale generated output and budget violations.
🤖 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 `@docs/taos-agent-manual.md`:
- Line 45: Update the markdown generation logic in scripts/build-agent-manual.py
to emit a blank line before each `---` separator, including separators in the
worked example and final iteration sections, so separators remain separate
blocks and do not underline preceding prose. Regenerate
docs/taos-agent-manual.md with the updated script.
---
Nitpick comments:
In `@CHANGELOG.md`:
- Around line 12-15: Add CI validation for the generated agent manual, comparing
the generated output against docs/taos-agent-manual.md and failing when the
compiled content exceeds the documented 18,000-character budget. Anchor the
check to the existing manual generation command or workflow configuration, and
ensure it detects both stale generated output and budget violations.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: fea12032-73e2-4e8c-9b4e-bc99378da388
📒 Files selected for processing (5)
CHANGELOG.mddocs/agent-manual/01-rules.mddocs/agent-manual/10-image-prompting.mddocs/agent-manual/index.mddocs/taos-agent-manual.md
| 5. THE WARNING SIGN: if you are chaining components to simulate something ONE CALL would do, stop and find the direct call. Async coordination faking synchronous request/response is a recurring anti-pattern here. | ||
| 6. Applies to WORKFLOWS AND PROCESSES too, not only code: monitoring, health checks, handoffs, escalation. | ||
|
|
||
| **Worked example**: an agent needed to know when a job finished, so it chained five moving parts -- a stream watcher, a spool file, a cron, a ticker, and a polling loop -- to simulate a return value by polling. One synchronous call to the job's status endpoint was the answer. The chain was auditable only by stitching four different logs, and failed in five different ways. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 4 -- 'build-agent-manual|rstrip|strip|---' scripts/build-agent-manual.pyRepository: jaylfc/taOS
Length of output: 1971
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== source files =="
git ls-files docs/agent-manual | sort
echo "== separator occurrences in source files =="
rg -n '^---$' docs/agent-manual || true
echo "== relevant output sections =="
sed -n '35,55p' docs/taos-agent-manual.md
sed -n '255,275p' docs/taos-agent-manual.mdRepository: jaylfc/taOS
Length of output: 3350
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
import re
src = Path('docs/agent-manual')
paths = sorted(src.rglob('*'))
text = re.sub(r'^<!-- .+ -->\n', '', ''.join(p.read_text() for p in paths if p.is_file()), flags=re.MULTIPLE).strip()
sections = [re.sub(r'^<!-- .+ -->\n', '', p.read_text(), flags=re.MULTILINE).strip() for p in paths]
body = '\n---\n\n'.join(sections)
output = "<!-- GENERATED from docs/agent-manual/ by scripts/build-agent-manual.py. Edit the source files, not this file. -->\n\n" + body + "\n"
output = re.sub(r"\n{3,}", "\n\n", output)
output = "\n".join(line.rstrip() for line in output.splitlines())
output = output.rstrip("\n") + "\n"
next20 = output.find('**Worked example**')
m1 = output.index('**Worked example**', next20)
m2 = output.index('This section covers', m1)
segment = output[m1-30:m2+80]
print(segment)
print("occurrences before generated-separator:", tuple(output.find(s) for s in ['**Worked example**', '-- WORKED EXAMPL --', 'This section covers', '**Final iteration**']))
print("precedes separator lines:")
for i, line in enumerate(output.splitlines(), 1):
if line == '---':
print(i, repr(output.splitlines()[i-2]) if i > 1 else '<none>', '---', repr(line))
PYRepository: jaylfc/taOS
Length of output: 278
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== source files =="
git ls-files docs/agent-manual | sort
echo "== separator occurrences in source files =="
rg -n '^---$' docs/agent-manual || true
echo "== relevant output sections =="
sed -n '35,55p' docs/taos-agent-manual.md
sed -n '255,275p' docs/taos-agent-manual.md
echo "== generated separator context =="
python3 - <<'PY'
from pathlib import Path
import re
paths = [Path(p) for p in open('/dev/stdin') if Path(p).is_file()]
sections = [re.sub(r'^<!-- .+ -->\n', '', p.read_text(), flags=re.MULTILINE).strip() for p in paths]
body = '\n---\n\n'.join(sections)
output = "\n".join([line.rstrip() for line in (
"<!-- GENERATED from docs/agent-manual/ by scripts/build-agent-manual.py. Edit the source files, not this file. -->\n\n" + body + "\n"
).splitlines()])
lines = output.splitlines()
for idx in [44, 240, 241, 265, 266, 267, 268, 269]:
print(idx, repr(lines[idx-1]), '---', repr(lines[idx]) if idx < len(lines)+1 else '<none>')
PY
git ls-files docs/agent-manual | sortRepository: jaylfc/taOS
Length of output: 3526
Keep separators on separate blocks so they do not underline prose.
The generated output has --- immediately after ended paragraphs in the worked example and final iteration sections. Add a blank line before each separator in scripts/build-agent-manual.py, then regenerate docs/taos-agent-manual.md so the next link does not render as a heading.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 45-45: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
🤖 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/taos-agent-manual.md` at line 45, Update the markdown generation logic
in scripts/build-agent-manual.py to emit a blank line before each `---`
separator, including separators in the worked example and final iteration
sections, so separators remain separate blocks and do not underline preceding
prose. Regenerate docs/taos-agent-manual.md with the updated script.
Source: Linters/SAST tools
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
1 participant
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.
CARD TITLE (intent, not commit subject): Agent guides: add the mechanical-simple-auditable design law
Autonomous build of board card tsk-kxbvup.
Add the design law to 01-rules.md with a worked example anonymised as
'an agent', link it from index.md, and rebuild the compiled manual. Trim
verbose prose in the image-prompting guide to stay within the compiled
manual 18000-char budget. Update CHANGELOG.
Files:
CHANGELOG.md | 7 +++
docs/agent-manual/01-rules.md | 13 +++++-
docs/agent-manual/10-image-prompting.md | 68 +++++++++++-----------------
docs/agent-manual/index.md | 2 +-
docs/taos-agent-manual.md | 79 +++++++++++++++------------------
5 files changed, 83 insertions(+), 86 deletions(-)
Summary by CodeRabbit