pub const SKILL_DOC: &str = r#"# turboreview review comments — agent guide
`turboreview` is a terminal code-review tool. A human reviewer leaves line
comments while reviewing a git diff. Comments are stored as JSON files under
`<repo>/.turboreview/`. As a coding agent, you read the open comments, make
the requested code changes, then write a response and update each comment's
status — all by editing the appropriate JSON file.
## Setup (in the target repository)
`turboreview` keeps its review state in a `.turboreview/` directory at the repo
root. This is local review metadata, not project source — add it to the
repository's `.gitignore` so it is never committed:
# .gitignore
.turboreview/
## File locations
### Working-tree review (Changes view)
Comments: `<repo-root>/.turboreview/comments.json`
Reviewed flags: `<repo-root>/.turboreview/reviewed.json`
These cover changes in the working tree (unstaged/staged files).
### Per-commit review (Commits-detail view)
Comments: `<repo-root>/.turboreview/commits/<sha>/comments.json`
Reviewed flags: `<repo-root>/.turboreview/commits/<sha>/reviewed.json`
Where `<sha>` is the full commit hash (40 hex characters) of the commit being
reviewed. Each commit gets its own isolated store.
### Activity log
`<repo-root>/.turboreview/comment-log.jsonl`
An append-only JSON-lines file. Each line is a JSON object written whenever a
comment is added or edited (not on relocation or load):
```json
{"path":"src/main.rs","line":42,"scope":"worktree","date":"2024-01-15 14:30:00","action":"set"}
{"path":"src/lib.rs","line":10,"scope":"commit:deadbeef1234...","date":"2024-01-15 14:30:05","action":"remove"}
```
Fields:
- `path` — repo-relative file path
- `line` — line number of the comment
- `scope` — `"worktree"` or `"commit:<sha>"` (full sha)
- `date` — date and time in `YYYY-MM-DD HH:MM:SS` format (UTC)
- `action` — `"set"` (added/edited) or `"remove"` (deleted)
**To find the latest review activity**, read `comment-log.jsonl` from the end
(tail). Each scope's actual comment data lives in the corresponding
`comments.json` (worktree or the commit's directory).
## Schema
Each element of the `comments.json` array is a comment object:
| field | type | meaning |
|------------------|-----------------|----------------------------------------------------------------|
| `file` | string (path) | repo-relative path of the file the comment is on |
| `line` | number | current line number (post-image / new-side line) of the comment|
| `hunk` | string | the diff hunk header for context, e.g. `@@ -1,4 +1,8 @@` |
| `text` | string | the reviewer's comment |
| `line_text` | string | the exact (trimmed) source line the comment was anchored to |
| `context_before` | array of string | up to 2 source lines immediately before (for relocation) |
| `context_after` | array of string | up to 2 source lines immediately after |
| `orig_line` | number | line number when the comment was first created |
| `stale` | bool | true if turboreview could not confidently relocate the comment |
| `status` | string | one of `open`, `resolved`, `wontfix`, `needs_info` |
| `response` | string or null | your reply to the reviewer |
| `updated` | number | unix epoch seconds of the last edit (0 for legacy comments without it) |
| `debug_snapshot` | object or null | read-only: call stack + locals captured at a breakpoint (do not edit) |
## Archive
Resolved comments may be moved to `.turboreview/archive/comments-archive.jsonl` to
keep the active `comments.json` small. This happens automatically on startup for
resolved comments older than 14 days, or manually when the reviewer presses `A`.
The archive file is **append-only JSON lines** — one serialized comment object per
line, same schema as the `comments.json` array elements above. Agents normally only
need the active `comments.json`; the archive is historical only.
## Your workflow
1. Check `comment-log.jsonl` (tail) to identify recent activity and which scope
(`worktree` or `commit:<sha>`) has open comments.
2. Read the appropriate `comments.json` (worktree or commit-specific).
3. For each comment with `status` == `open`:
- Use `file`, `line`, `line_text`, and `context_before`/`context_after` to locate
the exact spot in the code (line numbers may have shifted; `line_text` + context
are the reliable anchor).
- Read `text` — the requested change or question.
4. Make the code change that addresses the comment.
5. Update that comment object in the JSON:
- Set `response` to a short explanation of what you did (or why not).
- Set `status`:
- `resolved` — you made the requested change.
- `wontfix` — you deliberately did not change it; explain why in `response`.
- `needs_info` — you need clarification; ask in `response`.
- leave `open` only if you have not addressed it yet.
6. Write the JSON array back to the correct `comments.json` (preserve all other
fields and all other comments unchanged; pretty-printed JSON is fine).
## Rules
- NEVER delete a comment object or change `file`, `line`, `text`, `line_text`,
`context_*`, `orig_line`, `hunk`, or `debug_snapshot`. Only set `response` and
`status`. (`debug_snapshot`, when present, is captured runtime state — useful
context for understanding the comment; leave it untouched.)
- Preserve the JSON array structure and all comments you are not responding to.
- Keep `response` concise (1–3 sentences). It is shown to the reviewer in the TUI.
- The reviewer re-opens turboreview to see your `response` and `status` inline in
the diff.
- When editing a per-commit comment, write back to the commit-specific
`comments.json` at `.turboreview/commits/<sha>/comments.json` — not the
worktree file.
"#;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn skill_doc_contains_required_content() {
assert!(
SKILL_DOC.contains("comments.json"),
"SKILL_DOC must reference comments.json"
);
assert!(
SKILL_DOC.contains("status"),
"SKILL_DOC must mention status field"
);
assert!(
SKILL_DOC.contains("response"),
"SKILL_DOC must mention response field"
);
assert!(
SKILL_DOC.contains("open"),
"SKILL_DOC must mention open status"
);
assert!(
SKILL_DOC.contains("resolved"),
"SKILL_DOC must mention resolved status"
);
assert!(
SKILL_DOC.contains("wontfix"),
"SKILL_DOC must mention wontfix status"
);
assert!(
SKILL_DOC.contains("needs_info"),
"SKILL_DOC must mention needs_info status"
);
assert!(
SKILL_DOC.contains("comment-log"),
"SKILL_DOC must reference comment-log"
);
assert!(
SKILL_DOC.contains("commits/<sha>"),
"SKILL_DOC must describe per-commit path layout"
);
assert!(
SKILL_DOC.contains("archive"),
"SKILL_DOC must mention the archive"
);
assert!(
SKILL_DOC.contains("updated"),
"SKILL_DOC must mention the updated field"
);
}
}