backnotprop / backnotprop/plannotator

[Feature Request] Let guided review take custom project context (extends #955)

Open
#1,045 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
8.7k
Forks
649
Avg merge
11h 12m
Merged PRs (30d)
109

Description

## Context

The new Guided Review is great for orienting a reviewer through a big diff. But its section overviews are written by an agent that only sees the diff — it has no idea about my project's conventions, the vocabulary my team uses, or the design docs that explain *why* the code is shaped the way it is. I use a spec-driven workflow (GSD) whose docs carry exactly the "why this changeset exists / what it implies" context the guide is trying to reconstruct from scratch, and I'd love to point the guide at that context so the chapters speak my project's language instead of guessing.

Right now there's no way to do that. The guide methodology is the hardcoded `GUIDE_REVIEW_PROMPT` constant in `packages/server/guide/guide-review.ts`, and `buildCommand` only reads engine/model/effort knobs from `config` — there's no profile or skill hook. The source even calls this out next to `composeGuideMarkerPrompt`:

> guide has no custom-profile concept, so there is no "replace the methodology" branch.

This is the one gap between guide and code review. #897 asked for exactly this on the review side and you shipped it in **#955** — custom reviews as Agent Skills, `SKILL.md` read live from the global skill folders, becoming the review prompt. The guide just never got wired into that mechanism (`review-skill-loader.ts` / `resolveRequestedReviewProfile` have no guide equivalent).

## Why CLAUDE.md isn't enough

The guide runs as a `claude -p` subprocess in the repo, so `CLAUDE.md` is loaded ambiently and the prompt *does* permit an optional skim of `CLAUDE.md`/`AGENTS.md`. But the guide prompt aggressively de-emphasizes it — "Do NOT explore the repository," "stop after a third exploratory tool call," research budget ~90% the diff itself. So project context only lands if it happens to already be in `CLAUDE.md` *and* the model decides a section's "why" depends on it. It's incidental, not something I can steer per-project at the doc I actually want.

## Proposal

Extend the #955 custom-review-skill mechanism to Guided Review: a "Guide context" (or guide-skill) selector on the Agents tab, same source model as custom reviews (built-in / project / global `SKILL.md`).

One difference from review: a custom review fully replaces the default prompt. A custom guide should append, not replace, since guide output is schema-constrained. So the natural shape is:

```
GUIDE_REVIEW_PROMPT
+
+ user message (diff + changed files)
```

i.e. keep the organizer methodology and the schema contract intact, and inject the user's context as an extra section the model must honor while chaptering. Concretely that's a small change in `buildCommand`: resolve a `config.guideProfileId` (or reuse the existing skill loader), read the `SKILL.md` body, and splice it in where `GUIDE_REVIEW_PROMPT + "\n\n---\n\n" + userMessage` is composed — mirroring the marker/codex/claude branches the review path already has.

That gives project-aware section overviews ("this follows our GSD phase-17 replication contract" instead of "this appears to change replication") without touching the coverage/schema guarantees.

Happy to take this myself and open a PR if you're open to it — the review side (#955) already established the whole pattern, so this is mostly plumbing an existing mechanism into the guide path.

Contributor guide

Open the contributing guide

Research direction

Start in packages/server/guide/guide-review.ts, especially buildCommand, GUIDE_REVIEW_PROMPT, and composeGuideMarkerPrompt. Compare the existing review-skill-loader.ts and resolveRequestedReviewProfile flow established by #955, then trace how the Agents tab provides configuration. Done means Guided Review can select built-in, project, or global SKILL.md context while preserving the default methodology and schema contract.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.