Nmblr Revise

• Extract type and number from the DOC-ID argument
• Supported formats: RFC-0004, PRD-0001, PD-0003, ADR-0002, TD-0005, AD-0001, PPD-0001, TP-0001, TC-0001
• Parse into: type (e.g., RFC), number (e.g., 0004)
• Map type to config path key (see <document_resolution> section)

Step 3: Resolve document file path

• Use the documents paths from config.yaml to find the base directory for the document type
• Use Glob to find the file matching the pattern {base_dir}/{number}-*.md
• If no file found, report error and stop

Step 4: Read document and extract github_pr

• Read the document file
• Parse YAML frontmatter
• Extract the github_pr field
• If github_pr is empty or not set, fail with: "No PR found for {DOC-ID}. Run /nmblr:sync-github {DOC-ID} first to create a PR."
• Verify the PR is open:

  gh pr view {pr_number} --json state --jq '.state'
  

• If PR state is not "OPEN", fail with: "PR #{pr_number} is {state}. Cannot revise a {state} PR."

Step 5: Fetch PR review comments

• Fetch review comments using gh CLI:

  gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --jq '.[] | {id, path, line, body, user: .user.login, created_at, in_reply_to_id}'
  

• Also fetch top-level PR comments (non-review):

  gh pr view {pr_number} --json reviews --jq '.reviews[] | select(.state != "APPROVED") | {author: .author.login, body: .body, state: .state}'
  

• Filter out already-resolved threads and bot comments
• If no unresolved comments found, report: "No unresolved review comments on PR #{pr_number}. Nothing to revise." and stop

Step 6: Group comments by document section

• For inline review comments: use the line number from the comment to map to the nearest markdown section heading (## or ###)
• For top-level review comments: attempt to match keywords to document sections; default to "General"
• Present comments to the author in a structured format:

## Review Comments for {DOC-ID}

### Section: {section_name}

**Comment 1** by @{reviewer} ({type}):
> {comment_body}

Action: [Accept / Discuss / Defer / Dismiss]

**Comment 2** by @{reviewer} ({type}):
> {comment_body}

Action: [Accept / Discuss / Defer / Dismiss]

### Section: General
...

For each comment, identify the type:

• Suggestion: Comment proposes a specific change
• Question: Comment asks for clarification
• Concern: Comment raises an issue or risk
• Blocker: Comment indicates something must change before approval

Step 7: Process each comment based on author's choice

• Walk through each comment and ask the author how to handle it
• Apply the chosen action (see <comment_handling> section)

Step 8: Finalize changes

• Update the document changelog: bump the minor version (e.g., 1.1.0 -> 1.2.0)
• Add changelog entry: "{version} | {date} | {author} | Address review feedback"
• Update the version field in frontmatter to match
• Update the updated field in frontmatter to today's date
• Stage and commit:

  git add {document_file}
  git commit -m "docs: Revise {DOC-ID} -- address review feedback"
  

• Push to the existing PR branch:

  git push
  

• For accepted/dismissed comments, resolve the PR threads:

  gh api graphql -f query='mutation { minimizeComment(input: {subjectId: "{node_id}", classifier: RESOLVED}) { minimizedComment { isMinimized } } }'
  

• For discussed/deferred comments, reply to the thread:

  gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies -f body="{reply_text}"
  

• Report summary of actions taken </execution_instructions>

<comment_handling>

For each Accept action:

1. Show the current text of the affected section
2. Ask the author what change to make (or suggest one based on the comment)
3. Apply the edit using the Edit tool
4. Confirm the change with the author

For each Defer action:

1. Add to "Open Questions" section: - [ ] {summary of feedback} (from PR review by @{reviewer})
2. Reply to PR thread: "Deferred to Open Questions section for future consideration."

For each Discuss action:

1. Ask the author for their response
2. Post the reply to the PR thread

For each Dismiss action:

1. Ask the author for the dismissal reason
2. Reply to PR thread with the reason
3. Resolve the thread </comment_handling>

<document_resolution> To resolve a document ID to a file path:

1. Parse the ID: Split on - to get type and number

   • RFC-0004 -> type=RFC, number=0004
   • PRD-0001 -> type=PRD, number=0001

2. Map type to config path:

   Type	Config Key	Default Path
   RFC	documents.rfcs	docs/engineering/RFCs
   ADR	documents.adrs	docs/architecture/ADRs
   TD	documents.tds	docs/engineering/TDs
   AD	documents.ads	docs/architecture/ADs
   PRD	documents.prds	docs/product/PRDs
   PD	documents.pds	docs/project/PDs
   PPD	documents.ppds	docs/product/PPDs
   TP	documents.tps	docs/engineering/TPs
   TC	documents.tcs	docs/engineering/TCs

3. Find the file: Use Glob with pattern {path}/{number}-*.md

   • Example: docs/engineering/RFCs/0004-*.md

4. Validate: If no file matches, report error with the path searched </document_resolution>

<git_operations> Commit message format: