backnotprop / backnotprop/plannotator
[Feature Request] Guided Review: extra instructions + built-in output language
- 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
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