Create Pr

Create a PR

⚠️ MANDATORY: Issue Linking

Every PR MUST link to related issues and use closing keywords.

• PRs without issue links are incomplete
• Use Closes #X or Fixes #X to auto-close issues on merge
• Reference ALL related issues, even if not closing them

Instructions

Step 1: Identify Related Issues

# Check current branch name for issue hints
git branch --show-current

# Search for related issues
gh issue list --search "relevant keywords"

# View specific issue
gh issue view <number>

Find ALL issues this PR addresses:

• Issues explicitly being fixed
• Issues partially addressed
• Related issues for context

Step 2: Gather Context

# See what changed
git log main..HEAD --oneline
git diff main..HEAD --stat

# Get commit messages for context
git log main..HEAD --format="%s%n%b"

Step 3: Create PR with Issue Links

Use the writing-clearly-and-concisely skill for clear writing, then follow pr_guide.

IMPORTANT: Do NOT include "Generated with Claude Code" or similar tool attribution footers in PR descriptions.

gh pr create --title "[type]: [emoji] [description]" --body "$(cat <<'EOF'
[Two-sentence summary of what and why]

## Key Changes
- [Change 1]
- [Change 2]

## Related Issues

**Closes:**
- Closes #X - [brief description of what's fixed]
- Closes #Y - [brief description]

**Related (not closing):**
- Related to #Z - [why related]
- See also #W - [context]

## Testing
- [How it was tested]

## Files Changed
- [List key files]
EOF
)"

Issue Linking Keywords

GitHub recognizes these keywords to auto-close issues on merge:

Use format: Closes #X - brief description

Step 4: Verify Issue Links

After creating PR:

# Verify the PR shows linked issues
gh pr view <number> --json closingIssuesReferences

# Check the issue shows the PR link
gh issue view <number>

---

PR Description Template

[Two-sentence summary: what changed and why it was needed]

## Key Changes
- [Most important change]
- [Second important change]
- [Third important change]

## Related Issues

**Closes:**
- Closes #X - [what requirement this addresses]
- Fixes #Y - [what bug this fixes]

**Related:**
- Related to #Z - [provides context but doesn't close]

## Testing
- [Manual testing performed]
- [Automated tests added/passing]

## Architectural Impact
[If significant: explain system-wide effects]

## Files Changed
- `path/to/file1.ts` - [what changed]
- `path/to/file2.ts` - [what changed]

---

Anti-Patterns

❌ WRONG:
gh pr create --title "Fix bug" --body "Fixed the thing"

❌ WRONG:
"Related: #123" (no closing keyword, issue won't close)

❌ WRONG:
No mention of any issues at all

✅ CORRECT:
gh pr create --title "fix: 🔧 Resolve auth token expiration" --body "
Fixes session timeout by implementing token refresh.

## Related Issues
- Closes #123 - Auth token expires incorrectly
- Closes #124 - Users logged out unexpectedly
- Related to #100 - Auth system overhaul (partial)
"

---

Mermaid Diagrams in PRs

Use Mermaid diagrams to visualize changes, flows, and architectural impacts.

GitHub renders Mermaid natively. Include diagrams when:

• Showing before/after state changes
• Illustrating new data flows
• Explaining component interactions
• Depicting architectural changes

When to Include Diagrams

Example: PR with Diagram

````markdown

Key Changes

Added token refresh flow when session expires.

New Authentication Flow

sequenceDiagram
    participant C as Client
    participant A as Auth Service
    participant D as Database

    C->>A: Request with expired token
    A-->>C: 401 Token Expired
    C->>A: POST /refresh with refresh_token
    A->>D: Validate refresh token
    D-->>A: Token valid
    A-->>C: New access token
    C->>A: Retry original request
    A-->>C: 200 Success

Related Issues

• Closes #123 - Token expiration handling

````

Diagram Types for PRs

## Flow changes: flowchart
## API interactions: sequenceDiagram
## State machines: stateDiagram-v2
## Data models: erDiagram

Tips:

• Keep diagrams focused (5-10 nodes)
• Show the change, not entire system
• Before/after pairs are powerful
• Embed in PR body, not as links

---

Quick Reference

1. Find issues: gh issue list --search "keywords" 2. Create PR with closing keywords: Closes #X, Fixes #X 3. Always include: Related Issues section in PR body 4. Verify: gh pr view --json closingIssuesReferences 5. Add Mermaid diagrams for complex changes

Pull Request Style Guide

This document defines the standards for commit messages and PR descriptions.

Commit Messages

Format: Conventional commits with creative emoji narratives that tell a story

Structure: type: 🎭🌟 Description where emojis create an unexpected, literary narrative

Emoji Guidelines

• Avoid obvious combinations - no 🐛🔧 for bug fixes
• Tell cryptic stories - think literature, mythology, or abstract concepts
• Examples:
• feat: 🐋🎣 Implement large balance support (Whales = large balances, fishing = capturing users)
• fix: 🌙🔍 Resolve authentication edge cases (Night investigation = finding hidden bugs)
• refactor: 🏛️⚡ Restructure database connections (Ancient architecture gets lightning speed)
• When you think you're imaginative? BE MORE IMAGINATIVE! GO WILD!
• If you are lost, pick a format:
• 'a short story of what happened in this PR'
• 'a description of the final result'
• greek mythology
• art history

Title Guidelines

• Keep it short - Less than 50 characters
• Treat it like a book title - Should describe the whole PR in a few words
• No technobabble - Describe the goal over the changes, give the goal a name

Title Examples

• feat: 🐋🎣 Implement large balance support
• fix: 🌙🔍 Resolve authentication edge cases
• refactor: 🏛️⚡ Restructure database connections

Commit Types

• feat: - New features
• fix: - Bug fixes
• refactor: - Code restructuring without behavior changes
• docs: - Documentation updates
• chore: - Maintenance tasks

Pull Request Descriptions

Structure

1. Two-sentence summary - What and why, not how 2. Key changes list - Only the most impactful modifications 3. Additional changes section (if needed) - Secondary modifications 4. Testing notes - Validation approach 5. Related issues - ALWAYS MENTION related issues to close and refer to them where applicable 6. Architectural impact - System-wide effects 7. Future work - Any future work or improvements 8. Files changed - List of files that were modified

Writing Guidelines

• Focus on 'why' then 'how' - Explain motivation before implementation
• Professional yet friendly tone - Avoid overly elaborate language
• Legibility over completeness - Clear single sentences when possible
• NO "by claude code" mentions - Keep tool attribution out of descriptions
• Holistic view for large changes - Understand architectural implications
• ALWAYS CLOSE RELATED ISSUES - Mention related issues to close and refer to them where applicable

Example Template

TITLE: feat: 🧙⛓️ Implement dynamic chain support from blockchain provider registry

Brief description of what changed and why it was needed. Second sentence provides additional context about the business value or technical necessity.

Key Changes

• Implemented X to solve Y problem
• Refactored Z for better performance
• Added validation for edge case W

Additional Changes

• Updated documentation
• Fixed minor typos
• Adjusted logging levels

Testing

• Manual testing of core workflows
• Unit tests added for new functions
• Integration tests verify API contracts

Related Issues

• Closes #847
• Fixes #848

Architectural Impact

This change affects the authentication flow by introducing token caching, reducing API calls by ~40% and improving user experience during peak usage.

Files changed

• src/agents/standalone/prompt-selector.ts
• src/agents/standalone/workflows/steps/completion.ts