Skip to content

Adonis0123/adonis-skills / skills/review-prompt-composer

review-prompt-composer

Verified

Compose one repository-local, copy-ready Markdown prompt for another team or AI agent to review Git changes in the same working tree. Use for prompt-only requests covering committed ranges, staged, unstaged tracked, untracked, or all uncommitted changes when the reviewer can read the same repository and index. Persist under $repo_root/.review-handoff/prompts/ with branch-aware naming, 24-hour expiration, strict scope evidence, and a Review-Prompt-ID. Do not execute the review, run tests, modify reviewed code, commit, stage, stash, push, send the prompt, duplicate code, or use when the receiver lacks working-tree access. Use agentic-review-handoff to execute reviews, validate returned feedback, or run review-fix-re-review loops.

FileKindSize
SKILL.mdskill md11.5 KB
agents/openai.yamlconfig393 B
evals/evals.jsonconfig9.4 KB
evals/trigger-eval.jsonconfig3.2 KB
scripts/test_write_review_prompt.pyscript16.1 KB
scripts/write_review_prompt.pyscript23.3 KB

scripts/test_write_review_prompt.py

View on GitHub
#!/usr/bin/env python3
"""Black-box tests for write_review_prompt.py."""

from __future__ import annotations

import json
import importlib.util
import subprocess
import sys
import tempfile
import unittest
from datetime import datetime, timedelta, timezone
from pathlib import Path


SCRIPT_DIR = Path(__file__).resolve().parent
WRITER = SCRIPT_DIR / "write_review_prompt.py"
WRITER_SPEC = importlib.util.spec_from_file_location("review_prompt_writer", WRITER)
assert WRITER_SPEC is not None and WRITER_SPEC.loader is not None
WRITER_MODULE = importlib.util.module_from_spec(WRITER_SPEC)
sys.modules[WRITER_SPEC.name] = WRITER_MODULE
if WRITER.exists():
    WRITER_SPEC.loader.exec_module(WRITER_MODULE)

FIXED_NOW = datetime(2026, 7, 15, 6, 30, tzinfo=timezone.utc)
REVIEW_BODY = """# 审核任务:测试改动

## 工作区与范围

仓库与范围来自当前测试仓库。

生成时 scope digest:`{{SCOPE_DIGEST}}`

```bash
{{VERIFY_COMMAND}}
```

## 待验证目标

验证行为没有回归。

## 改动清单

1. `tracked.txt` — modified

## 审核重点

- 正确性与回归风险。

## 输出要求

审核结果第一行必须原样返回:

Review-Prompt-ID: `{{REVIEW_PROMPT_ID}}`
"""


class ReviewPromptWriterTest(unittest.TestCase):
    def setUp(self) -> None:
        self.temp_dir = tempfile.TemporaryDirectory()
        self.root = Path(self.temp_dir.name)
        self.repo = self.root / "repo"
        self.repo.mkdir()
        self.git("init", "-b", "main")
        self.git("config", "user.name", "Prompt Test")
        self.git("config", "user.email", "prompt@example.invalid")
        (self.repo / "tracked.txt").write_text("original\n", encoding="utf-8")
        self.git("add", "tracked.txt")
        self.git("commit", "-m", "initial")

    def tearDown(self) -> None:
        self.temp_dir.cleanup()

    def git(self, *args: str) -> subprocess.CompletedProcess[str]:
        return subprocess.run(
            ["git", *args],
            cwd=self.repo,
            check=True,
            capture_output=True,
            text=True,
        )

    def run_writer(
        self,
        scope: str,
        body_file: Path,
    ) -> subprocess.CompletedProcess[str]:
        return subprocess.run(
            [
                sys.executable,
                str(WRITER),
                "--repo",
                str(self.repo),
                "--scope",
                scope,
                "--body-file",
                str(body_file),
            ],
            check=False,
            capture_output=True,
            text=True,
        )

    def run_verify(self, prompt_path: Path) -> subprocess.CompletedProcess[str]:
        return subprocess.run(
            [
                sys.executable,
                str(WRITER),
                "--repo",
                str(self.repo),
                "--verify-prompt",
                str(prompt_path),
            ],
            check=False,
            capture_output=True,
            text=True,
        )

    def dirty_tracked_file(self) -> None:
        (self.repo / "tracked.txt").write_text("changed\n", encoding="utf-8")

    def create_direct(
        self,
        now: datetime,
        body: str = REVIEW_BODY,
    ):
        return WRITER_MODULE.create_review_prompt(
            self.repo,
            "all-uncommitted",
            body,
            now,
        )

    def prompt_body(self, path: Path) -> str:
        return path.read_text(encoding="utf-8").split("---\n", 2)[2]

    def test_writes_single_prompt_under_repo_local_branch_inbox(self) -> None:
        self.assertTrue(WRITER.exists(), "write_review_prompt.py must exist")
        self.dirty_tracked_file()
        body_file = self.root / "body.md"
        body_file.write_text(REVIEW_BODY, encoding="utf-8")

        result = self.run_writer("all-uncommitted", body_file)

        self.assertEqual(result.returncode, 0, result.stderr)
        payload = json.loads(result.stdout)
        prompt_path = Path(payload["prompt_path"])
        self.assertEqual(
            prompt_path.parent,
            self.repo.resolve() / ".review-handoff/prompts/active/main",
        )
        self.assertRegex(
            prompt_path.name,
            r"^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-all-uncommitted\.md$",
        )
        prompt = prompt_path.read_text(encoding="utf-8")
        self.assertIn("artifact_type: review_prompt", prompt)
        self.assertIn("format_version: 2", prompt)
        self.assertRegex(prompt, r'scope_digest: "[0-9a-f]{64}"')
        self.assertIn(f'prompt_id: "{payload["prompt_id"]}"', prompt)
        self.assertIn(f'Review-Prompt-ID: `{payload["prompt_id"]}`', prompt)
        self.assertNotIn("{{REVIEW_PROMPT_ID}}", prompt)
        self.assertNotIn("{{SCOPE_DIGEST}}", prompt)
        self.assertNotIn("{{VERIFY_COMMAND}}", prompt)
        self.assertEqual(len(payload["scope_digest"]), 64)
        self.assertNotIn("tracked.patch", prompt)
        self.assertNotIn("manifest.md", prompt)
        created_at = datetime.fromisoformat(payload["created_at"].replace("Z", "+00:00"))
        expires_at = datetime.fromisoformat(payload["expires_at"].replace("Z", "+00:00"))
        self.assertEqual((expires_at - created_at).total_seconds(), 24 * 60 * 60)
        self.assertNotIn(".review-handoff", self.git("status", "--short").stdout)

    def test_all_uncommitted_detects_index_drift_with_unchanged_worktree(self) -> None:
        tracked = self.repo / "tracked.txt"
        tracked.write_text("staged version one\n", encoding="utf-8")
        self.git("add", "tracked.txt")
        tracked.write_text("working version\n", encoding="utf-8")
        body_file = self.root / "body.md"
        body_file.write_text(REVIEW_BODY, encoding="utf-8")
        created = self.run_writer("all-uncommitted", body_file)
        self.assertEqual(created.returncode, 0, created.stderr)
        prompt_path = Path(json.loads(created.stdout)["prompt_path"])
        self.assertEqual(self.run_verify(prompt_path).returncode, 0)

        tracked.write_text("staged version two\n", encoding="utf-8")
        self.git("add", "tracked.txt")
        tracked.write_text("working version\n", encoding="utf-8")

        stale = self.run_verify(prompt_path)
        self.assertNotEqual(stale.returncode, 0)
        self.assertEqual(json.loads(stale.stdout)["reason"], "scope_digest_mismatch")

    def test_staged_same_path_content_drift_fails_digest_verification(self) -> None:
        (self.repo / "tracked.txt").write_text("staged version one\n", encoding="utf-8")
        self.git("add", "tracked.txt")
        body_file = self.root / "body.md"
        body_file.write_text(REVIEW_BODY, encoding="utf-8")
        created = self.run_writer("staged-only", body_file)
        self.assertEqual(created.returncode, 0, created.stderr)
        prompt_path = Path(json.loads(created.stdout)["prompt_path"])

        fresh = self.run_verify(prompt_path)
        self.assertEqual(fresh.returncode, 0, fresh.stderr)
        self.assertEqual(json.loads(fresh.stdout)["status"], "fresh")

        (self.repo / "tracked.txt").write_text("staged version two\n", encoding="utf-8")
        self.git("add", "tracked.txt")
        stale = self.run_verify(prompt_path)
        self.assertEqual(stale.returncode, 2, stale.stderr)
        payload = json.loads(stale.stdout)
        self.assertEqual(payload["status"], "stale")
        self.assertEqual(payload["reason"], "scope_digest_mismatch")
        self.assertNotEqual(payload["expected_digest"], payload["actual_digest"])

    def test_untracked_newline_path_content_drift_fails_verification(self) -> None:
        special_path = self.repo / "line\nbreak.txt"
        special_path.write_text("first\n", encoding="utf-8")
        artifact = WRITER_MODULE.create_review_prompt(
            self.repo,
            "untracked-only",
            REVIEW_BODY,
        )
        self.assertEqual(self.run_verify(artifact.prompt_path).returncode, 0)

        special_path.write_text("second\n", encoding="utf-8")
        stale = self.run_verify(artifact.prompt_path)
        self.assertEqual(stale.returncode, 2, stale.stderr)
        self.assertEqual(json.loads(stale.stdout)["reason"], "scope_digest_mismatch")

    def create_untracked_nested_repo(self) -> Path:
        nested = self.repo / "vendor-copy"
        nested.mkdir()
        subprocess.run(
            ["git", "init", "-b", "main", str(nested)],
            check=True, capture_output=True, text=True,
        )
        module = nested / "module.py"
        module.write_text("value = 1\n", encoding="utf-8")
        return module

    def test_nested_untracked_repo_cannot_be_silently_omitted_at_creation(self) -> None:
        self.create_untracked_nested_repo()
        body_file = self.root / "body.md"
        body_file.write_text(REVIEW_BODY, encoding="utf-8")
        for scope in ("untracked-only", "all-uncommitted"):
            with self.subTest(scope=scope):
                result = self.run_writer(scope, body_file)
                self.assertEqual(result.returncode, 1, result.stdout)
                self.assertIn("Unsupported untracked path", result.stderr)
                self.assertIn("vendor-copy/", result.stderr)
                self.assertIn("separate explicit review scope", result.stderr)
        self.assertFalse(list((self.repo / ".review-handoff/prompts/active").rglob("*.md")))

    def test_verifier_rejects_legacy_digest_that_omits_nested_repo(self) -> None:
        # The old writer omitted nested directories entirely. Creating before
        # the directory exists yields the same canonical bytes as that legacy
        # prompt, without embedding a second copy of the writer algorithm.
        artifacts = [WRITER_MODULE.create_review_prompt(self.repo, scope, REVIEW_BODY)
                     for scope in ("untracked-only", "all-uncommitted")]
        module = self.create_untracked_nested_repo()
        module.write_text("value = 999\n", encoding="utf-8")
        for artifact in artifacts:
            with self.subTest(scope=artifact.scope):
                result = self.run_verify(artifact.prompt_path)
                self.assertEqual(result.returncode, 1, result.stdout)
                self.assertIn("Unsupported untracked path", result.stderr)
                self.assertNotIn('"status": "fresh"', result.stdout)

    def test_staged_scope_excludes_nested_untracked_repo(self) -> None:
        self.dirty_tracked_file()
        self.git("add", "tracked.txt")
        module = self.create_untracked_nested_repo()
        body_file = self.root / "body.md"
        body_file.write_text(REVIEW_BODY, encoding="utf-8")
        result = self.run_writer("staged-only", body_file)
        self.assertEqual(result.returncode, 0, result.stderr)
        prompt = Path(json.loads(result.stdout)["prompt_path"])
        module.write_text("value = 999\n", encoding="utf-8")
        verified = self.run_verify(prompt)
        self.assertEqual(verified.returncode, 0, verified.stderr)
        self.assertEqual(json.loads(verified.stdout)["status"], "fresh")

    def test_ref_range_requires_and_persists_resolved_refs(self) -> None:
        (self.repo / "tracked.txt").write_text("second commit\n", encoding="utf-8")
        self.git("add", "tracked.txt")
        self.git("commit", "-m", "second")
        with self.assertRaisesRegex(WRITER_MODULE.WriterError, "requires both"):
            WRITER_MODULE.create_review_prompt(
                self.repo,
                "ref-range",
                REVIEW_BODY,
            )

        artifact = WRITER_MODULE.create_review_prompt(
            self.repo,
            "ref-range",
            REVIEW_BODY,
            base="HEAD^",
            target="HEAD",
        )
        self.assertRegex(artifact.scope_base, r"^[0-9a-f]{40}$")
        self.assertRegex(artifact.scope_target, r"^[0-9a-f]{40}$")
        self.assertNotEqual(artifact.scope_base, artifact.scope_target)
        self.assertEqual(self.run_verify(artifact.prompt_path).returncode, 0)

    def test_archives_expired_prompt_without_changing_body(self) -> None:
        self.dirty_tracked_file()
        first = self.create_direct(FIXED_NOW)
        original_body = self.prompt_body(first.prompt_path)

        second = self.create_direct(FIXED_NOW + timedelta(hours=25))

        archived = (
            self.repo.resolve()
            / ".review-handoff/prompts/archive/main"
            / first.prompt_path.name
        )
        self.assertFalse(first.prompt_path.exists())
        self.assertTrue(archived.exists())
        self.assertIn(
            "lifecycle_state: expired",
            archived.read_text(encoding="utf-8"),
        )
        self.assertEqual(self.prompt_body(archived), original_body)
        self.assertIn(archived, second.archived_paths)

    def test_keeps_unexpired_prompt_active(self) -> None:
        self.dirty_tracked_file()
        first = self.create_direct(FIXED_NOW)

        self.create_direct(FIXED_NOW + timedelta(hours=23))

        self.assertTrue(first.prompt_path.exists())
        self.assertIn(
            "lifecycle_state: active",
            first.prompt_path.read_text(encoding="utf-8"),
        )

    def test_collision_adds_numeric_suffix(self) -> None:
        self.dirty_tracked_file()
        first = self.create_direct(FIXED_NOW)

        second = self.create_direct(FIXED_NOW)

        self.assertNotEqual(first.prompt_path, second.prompt_path)
        self.assertTrue(
            second.prompt_path.name.endswith("-all-uncommitted-02.md"),
        )

    def test_malformed_active_prompt_is_preserved_and_reported(self) -> None:
        self.dirty_tracked_file()
        malformed = (
            self.repo
            / ".review-handoff/prompts/active/main/2026-07-14_06-30-broken.md"
        )
        malformed.parent.mkdir(parents=True)
        malformed.write_text(
            "---\nexpires_at: not-a-date\n---\nbroken\n",
            encoding="utf-8",
        )

        artifact = self.create_direct(FIXED_NOW)

        self.assertTrue(malformed.exists())
        self.assertTrue(
            any(malformed.name in warning for warning in artifact.warnings),
        )

    def test_mismatched_prompt_id_is_preserved_and_reported(self) -> None:
        self.dirty_tracked_file()
        first = self.create_direct(FIXED_NOW)
        content = first.prompt_path.read_text(encoding="utf-8")
        first.prompt_path.write_text(
            content.replace(
                f'prompt_id: "{first.prompt_id}"',
                'prompt_id: "other/2026-07-15_14-30-all-uncommitted"',
            ),
            encoding="utf-8",
        )

        artifact = self.create_direct(FIXED_NOW + timedelta(hours=25))

        self.assertTrue(first.prompt_path.exists())
        self.assertTrue(
            any("prompt_id does not match" in warning for warning in artifact.warnings),
        )

    def test_existing_unanchored_exclude_is_not_duplicated(self) -> None:
        self.dirty_tracked_file()
        exclude_file = self.repo / ".git/info/exclude"
        exclude_file.write_text(".review-handoff/\n", encoding="utf-8")

        self.create_direct(FIXED_NOW)

        self.assertEqual(
            exclude_file.read_text(encoding="utf-8"),
            ".review-handoff/\n",
        )

    def test_first_exclude_write_happens_before_scope_digest(self) -> None:
        self.dirty_tracked_file()
        protocol_file = self.repo / ".review-handoff/manual.txt"
        protocol_file.parent.mkdir(parents=True)
        protocol_file.write_text("protocol\n", encoding="utf-8")

        artifact = self.create_direct(datetime.now(timezone.utc))

        verified = self.run_verify(artifact.prompt_path)
        self.assertEqual(verified.returncode, 0, verified.stderr)
        self.assertEqual(json.loads(verified.stdout)["status"], "fresh")

    def test_sensitive_body_fails_without_printing_secret(self) -> None:
        self.dirty_tracked_file()
        secret = "https://alice:do-not-print@example.invalid/private"
        body = REVIEW_BODY.replace("验证行为没有回归。", secret)

        with self.assertRaises(WRITER_MODULE.WriterError) as raised:
            self.create_direct(FIXED_NOW, body)

        self.assertIn("credential-bearing URL", str(raised.exception))
        self.assertNotIn("do-not-print", str(raised.exception))
        prompt_root = self.repo / ".review-handoff/prompts"
        self.assertFalse(prompt_root.exists())


if __name__ == "__main__":
    unittest.main()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall