Cmd Pr Description

Instructions

1. Determine the base branch

First, determine the base branch using the repository's default branch.

Try these methods in order until one succeeds:

Method 1 - GitHub CLI

BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null)

Method 2 - Git remote

BASE_BRANCH=$(git remote show origin 2>/dev/null | grep "HEAD branch" | cut -d: -f2 | xargs)

Method 3 - Git symbolic-ref

BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

IMPORTANT: Do NOT assume master or main as a fallback. If all methods fail, ask the user which branch to use as the base.

2. Analyze the changes against the default branch

git diff $BASE_BRANCH --stat -- ":(exclude)*.lock" ":(exclude)package-lock.json" ":(exclude)pnpm-lock.yaml" ":(exclude)package.json"
git log $BASE_BRANCH..HEAD --oneline

3. Generate the title and description using the format below

Generate both a PR title (see Title Format) and the full description body (see Output Format).

Write the description to PR_DESCRIPTION.md and display both the title and description to the user.

4. Ask user to approve, edit, or reject

Use AskUserQuestion to present the generated title and description and ask the user to:

1. Approve as-is
2. Request changes (provide feedback, re-generate)
3. Reject (stop here)

Do NOT proceed to step 5 until the user explicitly approves.

5. On approval: commit, create/update PR

Once the user approves, execute the following steps in order:

Step 5a — Commit unstaged changes (if any):

git add -A && git commit -m "<generated title>"

If there are no unstaged/staged changes, skip this step.

Step 5b — Push the branch:

git push -u origin HEAD

Step 5c — Create or update the PR:

Check if a PR already exists for the current branch:

gh pr view --json number 2>/dev/null

If a PR exists, update it:

gh pr edit --title "<generated title>" --body "$(cat PR_DESCRIPTION.md)"

If no PR exists, create one:

gh pr create --title "<generated title>" --body "$(cat PR_DESCRIPTION.md)"

Title Format

PR titles must follow this format:

[KEYWORD] Summary

Rules:

• KEYWORD is an uppercase word that best categorizes the PR — not a fixed list. Common examples: FEAT, FEATURE, FIX, BUG, REFACTOR, TECHDEBT, DOCS, TEST, CHORE, PERF, PERFORMANCE, CI, BUILD, STYLE, CLI, CONFIG, MIGRATION, SECURITY, API, UI, INFRA
• Pick whichever keyword most accurately describes the PR — invent a new one if none of the above fit
• Summary is a concise imperative phrase (e.g., "Add session-based auth", "Fix null pointer in user lookup")
• Max 70 characters total
• No period at the end

Examples:

• [FEAT] Add session-based authentication
• [FIX] Resolve race condition in queue worker
• [REFACTOR] Simplify middleware chain
• [DOCS] Update API reference for v2 endpoints

Output Format

_tl;dr This is a single sentence summarizing the most important outcome of this PR in 100-200 characters._

## Summary

- **Subject/topic**: < 100 character explanation
- ...
- ...

## Feature Diff

| Component                          | Before                                     | After                                    |
| ---------------------------------- | ------------------------------------------ | ---------------------------------------- |
| 1-3 words describing the component | 1 sentence describing how it worked before | 1 sentence describing how it works after |
| ...                                | ...                                        | ...                                      |
| ...                                | ...                                        | ...                                      |

## Details

<details>
<summary>Technical Details</summary>

### Subsection Title

- **Subject/topic**: < 100 character explanation
- ...

### Another Subsection

- **Subject/topic**: < 100 character explanation
- ...

</details>

Section Rules

tl;dr

• Single sentence, max ~120 characters
• Product-level: what does the user/operator/developer get?
• No implementation details, no file names

Summary

• 2-5 bullets, one per meaningful change (not per file)
• Min (2) and max (5) are hard floors and ceilings per section
• Bold phrase answers "what does the user/operator get?"
• Plain language after the dash: one sentence, no jargon
• No implementation details: reviewers will read the diff for that
• No fluff: skip "minor cleanup", "refactor", "update docs" unless they deliver real value
• Start from the most impactful change and work down

Feature Diff

• Always include this section
• Should have anywhere from 1-10 rows depending on the size of the PR
• One row per component, module, config, API, or behavior that changed
• "Component" = the thing that changed (endpoint, table, config key, module, behavior, etc.)
• "Before" = previous state, or N/A if new
• "After" = new state, or Removed if deleted
• Keep cells concise — short phrases, not sentences
• Group related rows; aim for 3-10 rows
• Good component examples: API endpoint, DB table/column, config key, env var, dependency version, CLI flag, permission, error behavior

Details

• Only include for larger PRs (5+ files changed or multiple logical groups)
• Use collapsible <details> tags
• Group by feature/concern, not by file
• This is where implementation specifics go (file names, function names, migration details)
• Use backticks for code references (file.py, get_user(), /api/v1/users)
• 1-3 subsections, each with 3-5 bullets

General Details

• Use backticks for code references (file.py, get_user(), /api/v1/users)
• Italicize or bold keywords if it helps readability

Example Output

_tl;dr Users can now log in with email/password and stay authenticated across browser sessions._

## Summary

- **Session-based login**: Users authenticate with email/password and maintain sessions across browser restarts
- **Faster auth checks**: Session lookups use an indexed token column instead of scanning the full users table
- **Remember-me support**: Users can opt into 30-day sessions instead of the default 24-hour expiry

## Feature Diff

| Component        | Before                     | After                                           |
| ---------------- | -------------------------- | ----------------------------------------------- |
| Auth method      | API key only               | Email/password + session cookie                 |
| Session duration | N/A                        | 24 hours (default), 30 days (remember-me)       |
| `sessions` table | N/A                        | New table with `user_id`, `token`, `expires_at` |
| Token lookup     | Full table scan on `users` | Indexed lookup on `sessions.token`              |
| `/auth/login`    | N/A                        | New endpoint                                    |
| `/auth/logout`   | N/A                        | New endpoint                                    |

## Details

<details>
<summary>Technical Details</summary>

### Authentication Service

- **New login service**: Handles JWT issuance, session creation, and cookie management
- Add `login_service.py` with session create/validate/revoke methods
- Integrate `/auth/login` and `/auth/logout` endpoints in `routes/auth.py`
- Support `remember_me` flag to toggle 24h vs 30d expiry

### Database Schema

- **New sessions table**: Stores active sessions with automatic expiry
- Add `sessions` table with `user_id`, `token`, `expires_at` columns
- Add B-tree index on `token` for O(1) lookups
- Add index on `expires_at` for cleanup job performance

</details>