FP Review Skill

Ensure commits are properly linked to issues and provide review feedback.

Prerequisites

Before using fp commands, check setup:

bash
1# Check if fp is installed
2fp --version

If fp is not installed, tell the user:

The fp CLI is not installed. Install it with:

bash
1curl -fsSL https://setup.fp.dev/install.sh | sh -s

bash
1# Check if project is initialized
2fp tree

If project is not initialized, ask the user if they want to initialize:

This project hasn't been initialized with fp. Would you like to initialize it?

If yes:

bash
1fp init

Core Purpose

1. Verify commits are assigned to the correct issues
2. Leave review comments on issues
3. Open interactive review in the desktop app
4. Create stories — narrative documents that walk through code changes

Assigning Commits to Issues

Check Current Assignments

bash
1fp issue files <PREFIX>-X

If empty, the issue has no commits assigned.

Find Relevant Commits

bash
1jj log --limit 20        # Jujutsu
2git log --oneline -20    # Git

View Commit Details

bash
1jj show <commit-id>      # Jujutsu
2git show <hash> --stat   # Git

Match Commits to Issues

Compare:

• Files changed in commit vs issue description
• Commit message content vs issue title
• Code changes vs issue requirements

Assign Commits

Before assigning commits, confirm with the user. Some users prefer to work without committing until they're done, or may not want commits linked to issues.

Use AskUserTool to ask:

I found these commits that appear related to <PREFIX>-X:

• abc123 - Add user model
• def456 - Implement auth middleware

Would you like me to assign them to the issue? (If you prefer to review uncommitted changes instead, you can run fp review for the working copy.)

If confirmed:

bash
1# Single commit
2fp issue assign <PREFIX>-X --rev abc123
3
4# Multiple commits
5fp issue assign <PREFIX>-X --rev abc123,def456,ghi789
6
7# Current HEAD
8fp issue assign <PREFIX>-X
9
10# Reset and reassign
11fp issue assign <PREFIX>-X --reset
12fp issue assign <PREFIX>-X --rev abc123,def456

Verify Assignment

bash
1fp issue files <PREFIX>-X
2fp issue diff <PREFIX>-X --stat

Leaving Review Comments

Use fp comment for review feedback. Reference files and lines for specificity.

File-Specific Comments

bash
1fp comment <PREFIX>-X "**src/utils/parser.ts**: Consider extracting the validation logic into a separate function for testability."
2
3fp comment <PREFIX>-X "**src/api/handler.ts:45-60**: This error handling could swallow important exceptions. Suggest re-throwing after logging."

Severity Prefixes

Use prefixes to indicate importance:

bash
1fp comment <PREFIX>-X "[blocker] **src/auth.ts**: Missing input sanitization creates SQL injection risk."
2
3fp comment <PREFIX>-X "[suggestion] **src/utils.ts:23**: Could use optional chaining here for cleaner code."
4
5fp comment <PREFIX>-X "[nit] **README.md**: Typo in setup instructions."

• [blocker] - Must fix before merging
• [suggestion] - Recommended improvement
• [nit] - Minor/cosmetic issue

General Comments

bash
1fp comment <PREFIX>-X "Overall looks good. Main concern is the error handling in the API layer - see specific comments above."

Interactive Review (Desktop App)

fp review opens the Fiberplane desktop app for interactive diff review.

Requires the desktop app. If not installed: https://setup.fp.dev/desktop/latest/

Review Working Copy (No Commits Needed)

If the user hasn't committed yet (or prefers not to commit while work is in progress):

bash
1fp review

This shows all uncommitted changes in the working directory. No commit assignment required.

Review by Issue

bash
1fp review <PREFIX>-X

Note: For issue-based review to work, the issue must have commits assigned. If no commits are assigned, either:

1. Assign commits first with fp issue assign, OR
2. Use fp review to review the working copy instead

Review with Story

bash
1fp review <PREFIX>-X --with-story

Opens the review with the story panel visible alongside the diff. The issue must have a story created for it.

Other Review Targets

bash
1fp review git:abc123           # Specific git commit
2fp review jj:abc123            # Specific jj revision
3fp review git:abc123..def456   # Range of commits

Review Workflow

Step 1: Check Assignments

bash
1fp issue files <PREFIX>-X

Step 2: Assign Missing Commits

bash
1jj log --limit 20
2fp issue assign <PREFIX>-X --rev abc,def

Step 3: View the Diff

bash
1fp issue diff <PREFIX>-X --stat   # Overview
2fp issue diff <PREFIX>-X          # Full diff
3fp review <PREFIX>-X              # Open in desktop app

Step 4: Leave Comments

bash
1fp comment <PREFIX>-X "**file.ts:line**: feedback"

Stories

Stories are narrative documents that walk a reviewer through code changes. They combine markdown prose with embedded diffs, file excerpts, and chat transcripts.

Requires the experimental_story feature flag:

bash
1fp feature enable experimental_story

Creating a Story

bash
1# From a file
2fp story create <PREFIX>-X --file story.md
3
4# From stdin
5cat story.md | fp story create <PREFIX>-X

The first ## heading in the markdown becomes the story title.

Story Format

Stories are markdown documents that use directives to embed code artifacts:

Diff Directive

Shows file changes from the issue's assigned commits:

markdown
1## Moved validation to a shared module
2
3The old approach duplicated validation in each handler.
4
5:::diff{file="src/validation.ts"}
6Extracted from handler.ts and api.ts into a single module.
7:::

• file (required): relative path to the changed file
• The text between :::diff and ::: is the annotation — keep it to 1-2 sentences

File Directive

Shows file content (or a slice of it):

markdown
1:::file{path="src/config.ts" lines="10-25"}
2The new defaults that drive the behavior change.
3:::

• path (required): relative path to file
• lines (optional): line range, e.g. "10-25"

Chat Directive

Embeds excerpts from an AI coding session:

markdown
1:::chat{source="claude" session="/path/to/session.jsonl" messages="msg1,msg2"}
2The key design discussion that led to this approach.
3:::

• source: "claude", "pi", or "opencode"
• session: full path to session file
• messages: comma-separated message IDs

Writing Guidelines

• Headings are past-tense verbs — describe what was done, not what to do (e.g. "Moved validation to a shared module")
• Start with the user problem — the opening prose should explain why the change exists
• Show diff, then explain — lead with the :::diff directive, follow with the annotation
• Annotations are 1-2 sentences — brief context, not a full explanation

UI Support

Only :::diff is fully rendered in the desktop app right now. :::file works but the collapsed attribute is ignored. The hunks attribute on :::diff is also ignored.

Managing Stories

bash
1fp story list                    # List all stories in the project
2fp story get <story-id>          # Get story details (supports ID prefix)
3fp story get <PREFIX>-X          # Get story by issue ID
4fp story delete <story-id>       # Delete a story (supports ID prefix)
5fp story delete <story-id> --yes # Skip confirmation

One story per issue. Creating a new story for an issue replaces the previous one.

Quick Reference

Commands

bash
1# Check assignments
2fp issue files <PREFIX>-X
3
4# Assign commits
5fp issue assign <PREFIX>-X --rev <commits>
6
7# View changes
8fp issue diff <PREFIX>-X --stat
9fp issue diff <PREFIX>-X
10
11# Leave comments
12fp comment <PREFIX>-X "message"
13
14# Interactive review (desktop app)
15fp review <PREFIX>-X
16
17# Stories
18fp story create <PREFIX>-X --file story.md
19fp story list
20fp story get <PREFIX>-X
21fp story delete <story-id>
22fp review <PREFIX>-X --with-story

Comment Format

**filepath**: general comment about file
**filepath:line**: comment about specific line
**filepath:start-end**: comment about line range
[severity] **filepath**: prefixed comment

Severity Levels

• [blocker] - Must fix
• [suggestion] - Should consider
• [nit] - Minor issue