---
name: gitea-pr-review-cli
description: Use when an agent needs to fetch a single Gitea PR and produce or consume the project's review document format with strict version checks.
---

# gitea-pr-review CLI

## Overview
Use this skill when you need PR review context from Gitea in a stable document format for LLM workflows.

The CLI supports two output formats (`markdown`, `json`) and one strict schema version (`v1`). Version mismatch must be treated as a hard failure.

## When to Use

Use this skill when:
- You need to fetch one PR and convert it into LLM-friendly review documents.
- You need to re-render Markdown from a previously generated JSON file.
- You need deterministic output rules (numbering/version/header fields).

Do not use this skill when:
- You need cross-PR aggregation.
- You need full patch/diff bodies (this tool intentionally focuses on review context + diff stat).

## Required Inputs

For `fetch`, these environment variables are required:
- `GITEA_PR_CLI_API_TOKEN`
- `GITEA_PR_CLI_URL`
- `GITEA_PR_CLI_REPO`

## Quick Start

```bash
# 0) load env
source .local/env.sh

# 1) sanity check CLI document version contract
gitea-pr-review version
# expected: v1

# 2) fetch markdown to stdout (default)
gitea-pr-review fetch <pr-index>

# 3) fetch json to file
gitea-pr-review fetch <pr-index> --format json --out pr.json

# 4) render markdown from json
gitea-pr-review render-md --in pr.json --out pr.md
```

## Command Reference

### `fetch <pr-index>`
Fetch PR data from Gitea and output review document.

Options:
- `--format markdown|json` (default `markdown`)
- `--out <path>` (if omitted, write to stdout)

### `render-md --in <json_path>`
Render Markdown from existing JSON document.

Options:
- `--out <path>` (if omitted, write to stdout)

Important:
- Input JSON must have `version == "v1"`.
- If version mismatches, command exits non-zero.

### `version`
Print current document version string.

Expected output:
- `v1`

## Output Contract (v1)

Markdown header contains:
- Title line: `# <repo> #<pr> <title>`
- Numbering rule block
- `version: v1`
- `fetched at: <rfc3339>`
- PR description

JSON contains:
- Top-level `version: "v1"`
- `meta.fetched_at` (RFC3339 string)

Numbering hierarchy:
- Review: `<pr>.<review>`
- Comment: `<pr>.<review>.<comment>`
- Reply: `<pr>.<review>.<comment>.<reply>`

## Failure Handling

If `fetch` fails:
1. Check all required env vars are set.
2. Re-run with same env using a small PR index to isolate auth/connectivity issues.
3. Confirm repo slug format is `<owner>/<repo>`.

If `render-md` fails:
1. Validate JSON is generated by this CLI.
2. Validate `version` is exactly `v1`.
3. Check JSON is complete (`meta`, `reviews`, `threads`, `diff_stat`).

## Common Mistakes

- Running `fetch` without sourcing env file.
- Assuming schema compatibility across versions.
- Editing JSON `version` manually and expecting `render-md` to work.
- Treating position-only comments as lacking location; this CLI maps available position data to a displayed line when possible.