Skip to content

[Feature Request] plannotator guide import: open an authored guide in a review #2589

Closed

Description

@UberMouse

Use case

An agent writes a Guided Review of a PR itself (the guide.json + patch shape that plannotator guide export --guide --patch already accepts), then opens plannotator review so the reviewer can follow that guide next to the diff and comment.

Problem

An authored guide can be exported to HTML or shared to guides.show, but it cannot be opened in a review. The Guides panel lists only guides the review session generated or saved itself, and no CLI command or endpoint puts one there. plannotator guide has list, export, share and unshare, but no way in.

The only workaround is to write the saved-guide envelope by hand into <data dir>/guides/<repo key>/<id>.json plus <id>.patch, recomputing the repo key the way the session does. That is a private on-disk format, so it can break on any release.

Proposal

plannotator guide import --guide <guide.json> --patch <diff.patch | -> | --snapshot <snapshot.json> [--pr <url>]
  • It takes the same sources as export, validated the same way (buildAuthoredGuideSnapshot, parseGuideSnapshotJson).
  • It saves to the shelf the review session reads, keyed as the session keys it: --pr (or the snapshot's own PR URL), else the origin remote, else the repo directory. The PR also sets the label (PR #7); otherwise the label is the branch.
  • It prints the saved id. The next plannotator review of that repository lists the guide under Guides, and guide export --id / share --id work on it like on a generated guide.

Scope

I have a working prototype on UberMouse:context-notes, off main (d5fe10a): its last commit, d750d612e. The four commits before it are #2588. It is about 105 lines of source, 65 lines of tests and 3 lines of docs:

  • packages/shared/guide-store.ts: saveImportedGuide(), the inverse of buildSavedGuideSnapshot (patch first, then the envelope).
  • packages/server/guide/guide-cli.ts: runGuideImport, reusing parseSourceArgs / loadSnapshotSource; usage text.
  • apps/hook/server/cli.ts, the plannotator skill and the portable-guides page: one line each.
  • Tests in guide-cli.test.ts: a review session (createGuideStoreSession) of the same repository lists the imported guide, --pr files it under the PR's repository, and invalid input saves nothing.

Happy to open it as a PR.

Alternatives considered

  • plannotator review --guide guide.json: open the review with the guide already loaded, without saving it. That is nicer for a one-shot agent flow, but it needs a new launch option in both server runtimes and the review UI. import reuses the store and the Guides panel as they are, and a review flag could be added later on top of it.
  • POST /api/guides on a running review. Same runtime cost as above, and the guide is lost when the session ends unless it is also saved.
  • The Inbox's submit_guide (Plannotator Inbox: guided reviews from agents (step 5) #1760). It delivers a guide to the Inbox's read-only viewer, not to a review session where the reviewer comments on the diff.

Open questions

  • A review --patch-file session has no git context, so it shelves guides by directory (<dir>-<hash>), not by the origin remote. Import follows git and PR reviews, so a guide imported for a repository is not listed in a --patch-file review of the same checkout. Should --patch-file sessions read the cwd's remote when there is one, or should import take a --dir for that case?

  • Should import respect the guide-history setting (resolveGuideHistory) that gates autosave? The prototype always saves, since import is an explicit request.

  • Re-importing the same guide makes a second entry. Should it replace an earlier import with the same title and patch?


Posted by Claude Code

Activity

  1. backnotprop commented on Nov 4, 2026

    @backnotprop
    Owner

    Thanks for the clear write-up. Taking a look now.

  2. added a commit that references this issue on Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions