johba/disinto
1
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions
disinto/supervisor/best-practices/review-agent.md
openhands a66bd91721 fix: Replace Codeberg dependency with local Forgejo instance (#611) 
- Add setup_forge() to bin/disinto: provisions Forgejo via Docker,
  creates admin + bot users (dev-bot, review-bot), generates API
  tokens, creates repo, and pushes code — all automated
- Rename env vars: CODEBERG_TOKEN→FORGE_TOKEN, REVIEW_BOT_TOKEN→
  FORGE_REVIEW_TOKEN, CODEBERG_REPO→FORGE_REPO, CODEBERG_API→
  FORGE_API, CODEBERG_WEB→FORGE_WEB, CODEBERG_BOT_USERNAMES→
  FORGE_BOT_USERNAMES (with backwards-compat fallbacks)
- Rename API helpers: codeberg_api()→forge_api(), codeberg_api_all()
  →forge_api_all() (with compat aliases)
- Add forge_url field to project TOML; load-project.sh derives
  FORGE_API/FORGE_WEB from forge_url + repo
- Update parse_repo_slug() to accept any host URL, not just codeberg
- Forgejo data stored under ~/.disinto/forgejo/ (not in factory repo)
- Update all 58 files: agent scripts, formulas, docs, site HTML

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 16:57:12 +00:00

1.7 KiB
Raw Blame History

Review Agent Best Practices

Architecture

  • review-poll.sh (cron */10) → finds open PRs with CI pass + no review → spawns review-pr.sh
  • review-pr.sh uses claude -p to review the diff, posts structured comment
  • Uses review_bot forge account for formal reviews (separate from main account)
  • Skips WIP/draft PRs ([WIP] in title or draft flag)

Safe Fixes

  • Manually trigger review: bash ${FACTORY_ROOT}/review/review-pr.sh <pr-number>
  • Force re-review: bash ${FACTORY_ROOT}/review/review-pr.sh <pr-number> --force
  • Check review log: tail -20 ${FACTORY_ROOT}/review/review.log

Common Failures

  • "SKIP: CI=failure" — review bot won't review until CI passes. Fix CI first.
  • "already reviewed" — bot checks <!-- reviewed: SHA --> comment marker. Use --force to override.
  • Review error comment — uses <!-- review-error: SHA --> marker, does NOT count as reviewed. Bot should retry automatically.
  • Self-narration collapse — bot sometimes narrates instead of producing structured JSON. JSON output format in the prompt prevents this.
  • Hallucinated findings — bot may flag non-issues. This needs Clawy's judgment — escalate.

Monitoring

  • Unreviewed PRs with CI pass for >1h → supervisor-poll.sh auto-triggers review
  • Review errors should resolve on next poll cycle
  • If same PR fails review 3+ times → likely a prompt issue, escalate

Lessons Learned

  • Review bot must output JSON — prevents self-narration collapse
  • DISCUSS verdict should be treated same as REQUEST_CHANGES by dev-agent
  • Error comments must NOT include <!-- reviewed: SHA --> — would falsely mark as reviewed
  • Review bot uses forge formal reviews API — branch protection requires different user than PR author