Create Pr

Create a PR / MR

Platform-aware: This skill adapts to GitHub, Forgejo, or local tk workflows.

See skills/obsidian-plan-wiki/references/platform-detection.md for detection rules.

For local tk, this skill becomes "prepare for merge" — no remote PR needed.

⚠️ MANDATORY: Issue Linking

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

• PRs/MRs without issue links are incomplete
• GitHub / Forgejo: Use Closes #X or Fixes #X to auto-close issues on merge
• Local tk: Use tk dep / tk link to connect tickets
• Reference ALL related issues, even if not closing them

Instructions

Step 1: Identify Related Issues

Find ALL issues this PR/MR addresses:

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

GitHub:

git branch --show-current
gh issue list --search "relevant keywords"
gh issue view <number>

Forgejo:

git branch --show-current
# Use tea CLI or Forgejo API
tea issue list
tea issue view <number>

Local tk:

git branch --show-current
tk ls
tk show <id>

Step 2: Gather Context

# See what changed (platform-agnostic)
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/MR 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 any AI tool) or similar tool attribution footers in PR/MR descriptions.

GitHub:

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
)"

Forgejo:

# Use tea CLI or Forgejo API
tea pr create --title "[type]: [emoji] [description]" --description "..."
# Body format identical to GitHub — Forgejo recognizes the same closing keywords

Local tk:

# No remote PR needed — link tickets and prepare for local merge
tk link <task-id> <related-id>
tk dep <child-id> <parent-id>
tk add-note <task-id> "Ready to merge. Key changes: [summary]"

Issue Linking Keywords

GitHub and Forgejo recognize these keywords to auto-close issues on merge:

Use format: Closes #X - brief description

Local tk: Use tk dep <child> <parent> or tk link <a> <b> to connect tickets instead.

Step 4: Verify Issue Links

After creating PR/MR:

GitHub:

gh pr view <number> --json closingIssuesReferences
gh issue view <number>

Forgejo:

# Check PR body for Closes #X keywords
tea pr view <number>

Local tk:

# Verify ticket links/deps
tk show <id>

---

PR/MR 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]

Local tk note: When working locally, include this summary as a tk add-note on the task ticket instead of a PR body.

---

Anti-Patterns

❌ WRONG (any platform):
Creating a PR/MR with no description: --body "Fixed the thing"

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

❌ WRONG:
No mention of any issues at all

✅ CORRECT (GitHub):
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)
"

✅ CORRECT (Forgejo):
tea pr create --title "fix: 🔧 Resolve auth token expiration" --description "..."
# Same body format — Forgejo uses same closing keywords

✅ CORRECT (Local tk):
tk add-note <task-id> "Ready to merge: fixes auth token expiration"
tk link <task-id> <related-id>

---

Mermaid Diagrams in PRs/MRs

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

GitHub and Forgejo render Mermaid natively. Include diagrams when:

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

Local tk: Skip Mermaid diagrams — ticket notes are plain text.

When to Include Diagrams

Example: PR/MR 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/MRs

## 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/MR body, not as links

---

Quick Reference

GitHub

1. Find issues: gh issue list --search "keywords" 2. Create PR: gh pr create --title "..." --body "..." 3. Link issues: Closes #X, Fixes #X in body 4. Verify: gh pr view --json closingIssuesReferences

Forgejo

1. Find issues: tea issue list or Forgejo API 2. Create MR: tea pr create --title "..." --description "..." 3. Link issues: Closes #X, Fixes #X in body 4. Verify: tea pr view <N> — check body for keywords

Local tk

1. Find tasks: tk ls 2. No PR needed: prepare for local merge 3. Link tasks: tk dep <child> <parent> / tk link <a> <b> 4. Note summary: tk add-note <id> "Ready to merge: [summary]"

All platforms: Add Mermaid diagrams for complex changes (GitHub/Forgejo only)

Pull Request / Merge Request Style Guide

This document defines the standards for commit messages and PR/MR descriptions. Applies to GitHub PRs, Forgejo MRs, and local merge summaries alike.

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

PR/MR 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. GitHub and Forgejo: use Closes #X keywords. Local tk: use tk dep/tk link. 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. GitHub/Forgejo: Closes #X in body. Local tk: tk dep/tk link.

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