Pr Prep

Pull Request Preparation Workflow

Usage

Use this skill to stage changes and generate a PR summary. Run Skill(sanctum:git-workspace-review) first to capture the repository state and diffs.

Required Progress Tracking

Create TodoWrite items for these steps before starting: 1. pr-prep:workspace-reviewed 2. pr-prep:quality-gates 3. pr-prep:self-reviewed 4. pr-prep:changes-summarized 5. pr-prep:testing-documented 6. pr-prep:pr-drafted 7. pr-prep:content-verified

Mark each item as complete as the section is finished.

Step 1: Review Workspace (workspace-reviewed)

Confirm that Skill(sanctum:git-workspace-review) is complete. If changes were staged after the initial review, re-execute the skill to refresh the context.

Step 2: Run Quality Gates (quality-gates)

Execute formatting, linting, and tests using project-specific commands (e.g., make fmt, make lint, make test). Resolve all failures before proceeding. If a task cannot be executed locally, document the reason and the alternative validation performed. Language-specific commands and failure handling are detailed in modules/quality-gates.md.

Capabilities Reference Sync

If any plugin files changed (plugin.json, skills, commands, agents, or hooks), run make docs-sync-check to verify book/src/reference/capabilities-reference.md is current. If it reports discrepancies, run /sync-capabilities --fix or update the reference manually before proceeding.

Step 2.5: Self-Review Pass (self-reviewed)

Read the diff as if you are a reviewer seeing it for the first time. This catches scope creep, stale debug code, and unclear changes before anyone else spends time on them.

Automated checks:

# Check for debug statements left in
git diff --cached --name-only | xargs grep -nE \
  '(console\.log|print\(|debugger|TODO|FIXME|HACK|XXX)' \
  2>/dev/null || true

# Check for commented-out code blocks (3+ consecutive lines)
git diff --cached | grep -c '^+.*//.*[a-zA-Z]' || true

# Check for formatting-only commits mixed with feature work
git log --oneline $(git merge-base HEAD origin/master)..HEAD | \
  grep -iE '(fmt|format|lint|style|whitespace)' || true

Additive bias audit:

Run Skill(imbue:justify) to compute the additive bias score and check Iron Law compliance. If the score is YELLOW or above, justify each flagged signal before proceeding. If RED or STOP, rethink the approach.

Manual verification:

• [ ] Read the full diff: does every change serve the

stated goal?

• [ ] No debug statements or TODO markers left in
• [ ] No commented-out code blocks
• [ ] No formatting changes mixed with logic changes
• [ ] No fixup commits that should be squashed
• [ ] Additive bias score is GREEN or justified YELLOW
• [ ] Iron Law compliance: PASS (no test tampering)

If issues are found, fix them before proceeding.

Step 3: Summarize Changes (changes-summarized)

Use the notes from the workspace review and the output of git diff --stat origin/main...HEAD to understand the scope. Identify key points in the diffs and group them into 2-4 paragraphs highlighting the technical changes and their rationale. Note breaking changes, migrations, or documentation updates.

Step 4: Document Testing (testing-documented)

List each test command executed and its result. Include manual verification steps where relevant. If tests were skipped, document the reason and the mitigation plan.

Step 5: Draft the PR (pr-drafted)

Populate the standard template with Summary, Changes, Testing, and Checklist sections. Include issue references, screenshots, or follow-up TODO items. Template structure and examples are available in modules/pr-template.md.

Step 6: Verify Content Quality (content-verified)

Apply Skill(scribe:slop-detector) principles to the draft. Verify that the PR description avoids tier-1 slop words (delve, comprehensive, leverage, utilize, robust, seamless) and formulaic phrases like "I'd be happy to" or "It should be noted." Ensure there is no AI attribution in the text and that all claims are grounded with evidence such as commands, numbers, or filenames. Use active voice and maintain a balanced structure with prose for context.

Vocabulary Substitutions

• Replace leverage or utilize with use.
• Replace comprehensive with thorough or complete.
• Replace robust with solid or reliable.
• Replace facilitate with help or enable.
• Replace streamline with simplify.

Remediation

If the description contains slop, apply Skill(scribe:doc-generator) principles to ground claims with specifics, remove marketing language, and use direct statements.

Output Instructions

Write the final PR description to the specified path, then display the file path and its contents for confirmation.

Notes

Do not include tool or AI attribution in the PR text. If changes are required mid-process, re-run quality gates. This skill covers preparation; pushing changes and opening the PR occurs outside this workflow.

Supporting Modules

• TodoWrite patterns - naming conventions for sanctum TodoWrite items

Troubleshooting

If project-specific commands like make or npm are unavailable, verify the environment setup against the README. For permission errors, check write access to build directories. If a step fails without clear output, retry the command with verbose flags to inspect the logs.

Pull Request Template Structure

Standard Template Sections

1. Summary (Required)

Brief 1-2 sentence description of what the PR accomplishes and why.

Good Examples:

## Summary
Add support for modular skills to reduce token usage and improve skill maintainability through progressive loading.

## Summary
Fix authentication bug causing session timeout errors by implementing proper token refresh logic.

Avoid:

• Implementation details (save for Changes section)
• Vague descriptions like "various improvements"
• AI/tool attribution

2. Changes (Required)

Bullet list of specific changes grouped logically, explaining both what and why.

Structure:

## Changes
- **Category 1**: What changed and why
  - Sub-detail if needed
- **Category 2**: What changed and why
- **Breaking changes**: Highlight any breaking changes first

Good Examples:

## Changes
- **API**: Add `read_yaml()` and `to_pdf()` functions for symmetric I/O pattern
- **Session Management**: Introduce `ResumeSession` class to centralize configuration
- **Documentation**: Update README with new API examples and migration guide
- **Breaking**: Remove deprecated `generate_pdf()` function (use `to_pdf()` instead)

3. Testing (Required)

List each validation step taken, with commands and results.

Format:

## Testing
- `make test` - all 47 tests passing
- `make lint` - no warnings
- `pytest --cov` - 94% coverage (up from 89%)
- Manual verification: Tested PDF generation with 3 resume templates
- CI will run: cross-platform tests, integration tests

Include:

• Exact commands run
• Pass/fail status and counts
• Coverage changes if significant
• Manual testing performed
• What will run in CI (if different from local)

4. Checklist (Required)

Standard quality checklist for all PRs.

Template:

## Checklist
- [ ] Code follows project style guidelines
- [ ] Tests pass locally
- [ ] Documentation updated if needed
- [ ] Breaking changes documented (if applicable)

Extended Checklist (for complex PRs):

## Checklist
- [ ] Code follows project style guidelines
- [ ] Tests pass locally
- [ ] Tests added/updated for new functionality
- [ ] Documentation updated if needed
- [ ] Breaking changes documented (if applicable)
- [ ] Migration guide provided (if needed)
- [ ] Backward compatibility maintained (or breaking change justified)
- [ ] Performance impact assessed
- [ ] Security implications reviewed

Optional Sections

Screenshots/Visual Changes

For UI, CLI output, or visual changes:

## Screenshots
**Before:**
[screenshot or command output]

**After:**
[screenshot or command output]

Follow-up TODOs

For work deferred to future PRs:

## Follow-up Work
- [ ] Add integration tests for edge cases (Issue #123)
- [ ] Update deployment documentation
- [ ] Performance optimization for large files

Issue References

Link related issues:

Fixes #456
Related to #789
Part of #101

Migration Guide

For breaking changes:

## Migration Guide
**Before:**
\`\`\`python
generate_pdf(resume, "output.pdf")
\`\`\`

**After:**
\`\`\`python
resume.to_pdf("output.pdf")
\`\`\`

Performance Impact

For performance-related changes:

## Performance Impact
- PDF generation: 2.3s → 0.8s (65% improvement)
- Memory usage: 150MB → 45MB
- Benchmark results: [link to benchmark output]

Security Considerations

For security-related changes:

## Security Considerations
- Input validation added for all user-supplied paths
- Sanitization applied to template variables
- No secrets or credentials in code or tests

Best Practices for PR Descriptions

Do's

• Be concise but complete
• Focus on "why" not just "what"
• Use bullet points for scannability
• Include actual commands and results
• Link to relevant issues
• Highlight breaking changes prominently
• Use code blocks for examples
• Group related changes together

Don'ts

• Include AI/tool attribution
• Copy-paste entire file diffs
• Use vague descriptions
• Skip testing documentation
• Hide breaking changes in middle of list
• Include work-in-progress notes
• Reference internal tool commands unless relevant

Writing Quality (scribe Integration)

Apply scribe:doc-generator principles to avoid AI-sounding text:

Vocabulary to Avoid

Phrase Patterns to Remove

• "In order to..." → "To..."
• "It should be noted that..." → (just state it)
• "I'd be happy to..." → (not relevant in PR text)
• "This ensures that..." → (ground with specifics instead)
• Marketing language: "enterprise-ready", "cutting-edge", "best-in-class"

Quality Checklist

Before finalizing a PR description:

• [ ] No tier-1 slop words present
• [ ] All claims grounded with specifics (numbers, files, commands)
• [ ] Active voice used throughout
• [ ] No formulaic openers or closers
• [ ] Balanced structure (not all bullets)

Template Variations

Small Bug Fix

## Summary
Fix null pointer exception in PDF generation when resume has no education section.

## Changes
- Add null check before accessing education fields
- Add test case for resumes without education

## Testing
- `pytest tests/test_pdf_generation.py` - all passing
- Verified fix with sample resume lacking education section

## Checklist
- [x] Code follows project style guidelines
- [x] Tests pass locally
- [x] Documentation updated if needed
- [x] Breaking changes documented (if applicable)

Feature Addition

## Summary
Add support for exporting resumes to HTML format alongside existing PDF export.

## Changes
- **Core API**: Add `to_html()` method to Resume class
- **Templates**: Create Jinja2 HTML templates matching PDF layouts
- **Testing**: Add HTML generation tests and snapshot testing
- **Documentation**: Update README with HTML export examples

## Testing
- `make test` - 52 tests passing (added 5 new tests)
- `make lint` - no warnings
- Manual verification: Generated HTML from 4 resume templates, verified in Chrome/Firefox
- Snapshot tests validate HTML output consistency

## Checklist
- [x] Code follows project style guidelines
- [x] Tests pass locally
- [x] Documentation updated if needed
- [x] Breaking changes documented (if applicable)

Quality Gates Pattern Reference

Common Quality Gate Commands by Language

Python Projects

# Formatting
make format          # or: black . && isort .
ruff format .
uv run ruff format .

# Linting
make lint            # or: ruff check .
mypy .
pylint src/

# Testing
make test            # or: pytest
pytest --cov=src --cov-report=term
uv run pytest

JavaScript/TypeScript Projects

# Formatting
npm run format       # or: prettier --write .
yarn format

# Linting
npm run lint         # or: eslint .
yarn lint

# Testing
npm test
yarn test
jest --coverage

Go Projects

# Formatting
go fmt ./...
gofmt -w .

# Linting
golangci-lint run
go vet ./...

# Testing
go test ./...
go test -v -cover ./...

Rust Projects

# Formatting
cargo fmt

# Linting
cargo clippy -- -D warnings

# Testing
cargo test
cargo test --all-features

Failure Handling Patterns

When Quality Gates Fail

1. Capture the exact error output - Don't summarize, show actual failures 2. Fix failures immediately - Never proceed with failing tests 3. Re-run after fixes - Confirm all gates pass before continuing 4. Document what was fixed - Include in PR testing section

Common Failure Categories

• Formatting issues: Auto-fix with formatter, then re-run
• Linting warnings: Address or document why they're acceptable
• Test failures: Fix the code or update tests as needed
• Type errors: Resolve type mismatches or add proper annotations

Alternative Validation Approaches

When Local Tests Can't Run

• Missing dependencies: Document what's missing and CI strategy
• Environment constraints: Note platform-specific limitations
• Integration tests: Explain which will run in CI only
• Manual verification: Document steps taken locally instead

CI/CD Integration Notes

## Testing
- Local: `make test` - all unit tests passing
- CI will run: integration tests, E2E tests, cross-platform builds
- Manual verification: Tested CLI commands locally on Ubuntu 22.04

Quality Gate Checklist

• [ ] Formatting passes (no diffs after format command)
• [ ] Linting passes (no warnings or errors)
• [ ] All tests pass locally
• [ ] Type checking passes (if applicable)
• [ ] Build succeeds (if applicable)
• [ ] Manual smoke testing completed

Special Cases

Pre-commit Hooks

If project has pre-commit hooks:

pre-commit run --all-files

Document any hooks that were run.

Multiple Test Suites

# Unit tests
pytest tests/unit/

# Integration tests
pytest tests/integration/

# E2E tests (may run in CI only)
# Skipped locally - runs in CI environment

Performance Tests

Note if performance benchmarks exist but weren't run:

## Testing
- Unit tests: passing
- Performance benchmarks: skipped (run in dedicated CI job)

TodoWrite Patterns for Sanctum

Naming Convention

All sanctum skills follow a consistent pattern for TodoWrite items:

<skill-name>:<step-name>

The skill name matches the frontmatter name field, and the step name describes the specific workflow phase.

Examples from Sanctum Skills

git-workspace-review

git-review:repo-confirmed
git-review:status-overview
git-review:diff-stat
git-review:diff-details

commit-messages

Commit messages skill does not use TodoWrite as it's a single-step artifact generation workflow.

pr-prep

pr-prep:workspace-reviewed
pr-prep:quality-gates
pr-prep:self-reviewed
pr-prep:changes-summarized
pr-prep:testing-documented
pr-prep:pr-drafted
pr-prep:content-verified

doc-updates

doc-updates:context-collected
doc-updates:targets-identified
doc-updates:consolidation-checked
doc-updates:edits-applied
doc-updates:guidelines-verified
doc-updates:accuracy-verified
doc-updates:preview

version-updates

version-update:context-collected
version-update:target-files
version-update:version-set
version-update:docs-updated
version-update:verification

Task Deletion (Claude Code 2.1.20+)

TaskUpdate now supports deleting tasks. Use deletion to clean up completed workflow items and reduce clutter in the /tasks view.

2.1.21 fix: Task IDs are no longer reused after deletion. On 2.1.20, deleting a task and creating a new one could silently reuse the same ID, leaking old state into new tasks. Upgrade to 2.1.21+ if using task deletion.

When to Delete

• After a workflow completes successfully and all items are marked done
• Stale items from interrupted or abandoned workflows
• Temporary tracking items that served their purpose

When NOT to Delete

• Items that serve as audit trails (proof-of-work items)
• Items referenced by other active workflows
• Items the user may want to review later

Deletion Pattern

# After workflow completion, clean up tracking items:
TaskUpdate(id: "pr-prep:workspace-reviewed", delete: true)
TaskUpdate(id: "pr-prep:quality-gates", delete: true)

Recommended Approach

Create → Complete → (optionally) Delete stale items after workflow success. Keep proof-of-work and audit items intact.

Best Practices

Step Naming

• Use present tense verbs (collected, identified, applied, verified)
• Keep names concise (2-3 words max)
• Make the outcome clear from the name
• Order steps sequentially in the workflow

When to Skip TodoWrite

• Single-step workflows (like commit-messages)
• Quick utilities that complete in one operation
• Read-only analysis with no discrete phases

Integration

• Create all TodoWrite items at workflow start
• Mark items complete immediately after finishing each step
• Use TodoWrite as workflow documentation for users