backnotprop / backnotprop/plannotator

[Feature Request] Guided Review: extra instructions + built-in output language

Open
#1,265 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

Guided Review is great for chaptering a large diff, but the organizer prompt is fixed English prose (`GUIDE_REVIEW_PROMPT` in `packages/server/guide/guide-review.ts`) with no way to steer tone, standing preferences, or **output language**. Code review already has custom skills (#955); guides explicitly do not — the compose path next to `composeGuideMarkerPrompt` notes there is no custom-profile / “replace the methodology” branch.

I want something more general than “point the guide at one project doc”: either freeform **extra instructions** that append to the built-in methodology, and/or a **built-in language** control so titles / intent / overviews / summaries come out in French (or another language) while file paths and identifiers stay unchanged.

Related: #1045 asks to append project context via a guide-skill selector (same append-not-replace shape). Complementary, not a substitute — language especially should not require inventing a skill. Also adjacent to #1253 (UI locale); this issue is only about **guide generation output**, not chrome i18n.

## Why existing knobs aren't enough

- `~/.plannotator/config.json` → `prompts` only customizes post-decision feedback to the calling agent. Docs already say it does not replace instructions for launched AI jobs.
- Custom review skills replace the **code review** prompt; they are not wired for Guided Review, and fully replacing the guide methodology would risk the schema / coverage contract guides depend on.
- The guide prompt’s research budget de-emphasizes ambient `CLAUDE.md` / `AGENTS.md`, so “just put Write in French in AGENTS.md” is incidental at best.

## Proposal

Keep `GUIDE_REVIEW_PROMPT` and the schema / marker contracts intact. Append user steering before the user message (diff + changed files), roughly:

```text
GUIDE_REVIEW_PROMPT
+ [optional language directive]
+ [optional extra instructions]
+ [optional guide-skill / project context from #1045]
+ user message
```

**Extra instructions** — any durable surface is fine: `config.json` (e.g. `guide.extraInstructions`), an Agents-tab textarea, and/or the guide-skill append from #1045. Append only; never replace the organizer methodology.

**Built-in language** — first-class control (config and/or picker next to Guided Review launch), e.g. `guide.language: "fr"`. Plannotator injects a short directive: write every human-readable guide string in that language; keep paths/symbols; keep JSON schema and “every changed file exactly once” coverage unchanged. Default / unset = today’s English behavior.

Happy to bikeshed naming (`extraInstructions` vs `instructions`, `language` vs `locale`) if you have a preferred config shape.

Contributor guide

Open the contributing guide

Research direction

Start in packages/server/guide/guide-review.ts, reading GUIDE_REVIEW_PROMPT and the compose path near composeGuideMarkerPrompt. Trace how Guided Review receives configuration and launches, including the durable config or Agents-tab surfaces mentioned. Done means optional extra instructions and language steering are appended without replacing the methodology, while schema, marker contracts, paths, identifiers, and changed-file coverage remain intact.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.