nybble-pr

Generate a well-structured pull request from the current spec's artifacts and manage it via the GitHub CLI (gh).

1. Detect existing PR

Steps:

1. Get the current branch: git branch --show-current.
2. Check for an existing PR: gh pr list --head <branch> --json number,title.
3. If a PR exists, switch to UPDATE mode. Otherwise, CREATE mode.

2. Gather PR content

Read these files from the active spec directory:

• spec.md — for the summary and scope.
• progress.md — for completed tasks.
• evidence/ — for build, test, coverage, and security scan results.
• suggestions.md — for any implementation notes.
• design-context.md — for design references if present.

3. Generate PR description

Structure the description using this format:

markdown
1## Summary
2<!-- 2-3 sentences from spec.md summary -->
3
4## Backend Changes
5<!-- List backend changes from progress.md completed tasks -->
6
7## Frontend Changes
8<!-- List frontend changes from progress.md completed tasks -->
9
10## Automated Testing
11<!-- ONLY reference what the test suite actually validated -->
12<!-- Pull from evidence/test-results.txt and evidence/coverage-summary.txt -->
13- Tests: <passed>/<total> passing
14- Coverage: <N>% lines
15
16## Security
17<!-- Pull from evidence/security-scan.txt if available -->
18
19## Manual Verification
20<!-- Leave as placeholder for human to fill in -->
21- [ ] (Add manual test steps here)
22
23## Spec Reference
24- Spec: `.nybble/specs/active/<feature>/spec.md`

4. Create or update PR

CREATE mode

• Run: gh pr create --title "<feature title>" --body "<description>"
• Use the spec's feature name as the PR title (cleaned up for readability).
• Log a pr_created event to events.jsonl.

UPDATE mode

• Run: gh pr edit <number> --body "<description>"
• Preserve any human-added content in the Manual Verification section.
• Log the update in event details.

5. Post-creation

After the PR is created or updated:

• Print the PR URL for the human.
• If evidence shows failing tests or security issues, add a comment noting the known issues.

Trust Behavior

• L1-L2 (observer, collaborator): Show the full PR description to the human and wait for approval before running gh pr create.
• L3+ (architect, autonomous): Create the PR directly, then present the URL and description for review.

File Locations

• Spec artifacts: .nybble/specs/active/<feature>/
• Event log: .nybble/events.jsonl
• PR tool: gh CLI (must be installed and authenticated)

What This Skill Does NOT Do

• Merge PRs — merging is a human decision.
• Fill in manual verification — that section is for the human.
• Run CI — it references CI results from evidence, but does not trigger CI pipelines directly.
• Handle merge conflicts — if conflicts exist, notify the human.

Project Context

• CORE.md: .nybble/memory/CORE.md
• Domain files: .nybble/foundation/domains.yaml
• Design principles: Clarity, Consistency
• Workflow skills: nybble-spec-create, nybble-spec-edit, nybble-run, nybble-fix, nybble-skill-extract, nybble-conventions, nybble-domains, nybble-design, nybble-security, nybble-events, nybble-verify, nybble-curate-feedback, nybble-pr, nybble-build-verify
• Project pattern skills: .nybble/skills/ (populated after features ship)