adynato-github

# GitHub Skill

Use this skill when working with GitHub on Adynato projects.

## Always Use gh CLI

Use the `gh` CLI for all GitHub operations instead of the web interface:

```bash
# Create PR
gh pr create --title "Title" --body "Description"

# View PR
gh pr view 123

# Check PR status
gh pr checks 123

# Merge PR
gh pr merge 123 --squash
```

## PR Descriptions

Every PR must have a thorough description. Use this template:

```bash
gh pr create --title "feat: add user authentication" --body "$(cat <<'EOF'
## Summary

Brief description of what this PR does and why.

- Added JWT-based authentication flow
- Implemented login/logout endpoints
- Added auth middleware for protected routes

## Changes

- `lib/auth.ts` - Auth utilities and token management
- `app/api/auth/login/route.ts` - Login endpoint
- `app/api/auth/logout/route.ts` - Logout endpoint
- `middleware.ts` - Route protection

## Testing

- [ ] Login with valid credentials returns token
- [ ] Login with invalid credentials returns 401
- [ ] Protected routes reject unauthenticated requests
- [ ] Logout invalidates token

## Screenshots

(if UI changes)

## Related

- Closes #123
- Part of #456
EOF
)"
```

### Required Sections

| Section | When Required | Purpose |
|---------|---------------|---------|
| **Summary** | Always | What and why in 2-3 sentences |
| **Changes** | Always | List of files/areas modified |
| **Testing** | Always | How to verify it works |
| **Screenshots** | UI changes | Visual proof of changes |
| **Related** | If applicable | Linked issues/PRs |

## Stacked PRs

For large deliverables, break work into small, stacked PRs that build on each other.

### Why Stack PRs

- **Easier review** - Reviewers can focus on one concern at a time
- **Faster merges** - Small PRs get approved faster
- **Lower risk** - Each PR is independently deployable
- **Better history** - Clear progression of changes

### Stacking Strategy

For a feature like "Add user dashboard":

```
PR 1: Add user API endpoints (base)
  ↓
PR 2: Add dashboard data fetching (stacked on PR 1)
  ↓
PR 3: Add dashboard UI components (stacked on PR 2)
  ↓
PR 4: Add dashboard tests (stacked on PR 3)
```

### Creating Stacked PRs

```bash
# PR 1: Base branch
git checkout -b feat/user-api
# ... make changes ...
git push -u origin feat/user-api
gh pr create --base main --title "feat: add user API endpoints"

# PR 2: Stack on PR 1
git checkout -b feat/dashboard-data feat/user-api
# ... make changes ...
git push -u origin feat/dashboard-data
gh pr create --base feat/user-api --title "feat: add dashboard data fetching"

# PR 3: Stack on PR 2
git checkout -b feat/dashboard-ui feat/dashboard-data
# ... make changes ...
git push -u origin feat/dashboard-ui
gh pr create --base feat/dashboard-data --title "feat: add dashboard UI"
```

### Stack Description

In stacked PRs, note the relationship:

```markdown
## Summary

Adds dashboard UI components.

## Stack

This PR is part of a stack:
1. #101 - Add user API endpoints ← **merged**
2. #102 - Add dashboard data fetching ← **base**
3. **#103 - Add dashboard UI** ← you are here
4. #104 - Add dashboard tests

Please review and merge in order.
```

### Updating Stacked PRs

When the base PR changes:

```bash
# Update your branch with changes from base
git checkout feat/dashboard-ui
git rebase feat/dashboard-data
git push --force-with-lease
```

When base PR merges:

```bash
# Rebase onto new base
git checkout feat/dashboard-data
git rebase main
git push --force-with-lease

# Update PR base branch
gh pr edit 102 --base main
```

## PR Size Guidelines

| Size | Lines Changed | Review Time | Recommendation |
|------|---------------|-------------|----------------|
| XS | < 50 | Minutes | Ideal |
| S | 50-200 | < 1 hour | Good |
| M | 200-500 | 1-2 hours | Acceptable |
| L | 500-1000 | 2-4 hours | Split if possible |
| XL | > 1000 | Days | Must split |

**Target: Keep PRs under 300 lines changed.**

## Commit Messages

Use conventional commits:

```bash
feat: add user authentication
fix: resolve login redirect loop
docs: update API documentation
refactor: extract auth utilities
test: add auth endpoint tests
chore: update dependencies
```

Format:
```
<type>: <short description>

<optional body explaining why>

<optional footer with references>
```

## Branch Naming

```
feat/short-description    # New features
fix/issue-description     # Bug fixes
refactor/what-changed     # Code refactoring
docs/what-documented      # Documentation
test/what-tested          # Test additions
```

## Common gh Commands

```bash
# Create PR with labels
gh pr create --title "feat: thing" --label "enhancement" --label "needs-review"

# Create draft PR
gh pr create --title "wip: thing" --draft

# Request reviewers
gh pr edit 123 --add-reviewer @username

# Check CI status
gh pr checks 123 --watch

# View PR diff
gh pr diff 123

# Checkout PR locally
gh pr checkout 123

# Close PR
gh pr close 123

# Reopen PR
gh pr reopen 123

# List open PRs
gh pr list

# View PR comments
gh pr view 123 --comments
```

## Review Process

1. **Self-review first** - Read your own diff before requesting review
2. **CI must pass** - Don't request review until checks are green
3. **Respond to feedback** - Address or discuss all comments
4. **Squash on merge** - Keep main history clean

```bash
# Merge with squash (preferred)
gh pr merge 123 --squash --delete-branch

# Merge with rebase (for stacks)
gh pr merge 123 --rebase --delete-branch
```

## Addressing PR Comments

When fixing review comments, follow this workflow for **each comment**:

### 1. Make Individual Commits

Create a separate conventional commit for each review comment fix:

```bash
# Fix first comment
git add src/auth.ts
git commit -m "fix: add null check for user token

Addresses review comment about potential null reference"

# Fix second comment
git add src/api/users.ts
git commit -m "refactor: extract validation logic to separate function

Addresses review comment about function complexity"

# Fix third comment
git add src/utils.ts
git commit -m "fix: handle edge case for empty array

Addresses review comment about missing edge case handling"
```

**Do NOT batch multiple comment fixes into one commit.** Each fix should be atomic and traceable.

### 2. Reply to the Comment

After committing the fix, reply to the review comment:

**If fixed:**
```
Fixed in <commit-sha>
```

Or with more context:
```
Fixed in abc1234 - added null check before accessing token property.
```

**If not valid or won't fix:**
```
I don't think this change is necessary because [reason].

[Explanation of why current implementation is correct/preferred]
```

Or:
```
This is intentional - [explanation]. Happy to discuss further if you disagree.
```

### 3. Resolve the Comment

After replying, resolve the conversation:

```bash
# View comments to get comment IDs
gh api repos/{owner}/{repo}/pulls/{pr}/comments

# Or use the web UI to resolve after replying
```

In the GitHub web UI: Click "Resolve conversation" after your reply.

### Complete Workflow Example

```bash
# 1. Read all comments
gh pr view 123 --comments

# 2. For each valid comment, fix and commit individually
git add src/auth.ts
git commit -m "fix: validate token expiry before use

Addresses review feedback on auth token handling"

# 3. Push all fixes
git push

# 4. Reply to each comment in GitHub UI or via API
gh api repos/adynato/myrepo/pulls/123/comments/456789/replies \
  -f body="Fixed in $(git rev-parse --short HEAD)"

# 5. Resolve each conversation in GitHub UI
```

### Comment Response Templates

| Scenario | Response |
|----------|----------|
| Fixed | "Fixed in `abc1234`" |
| Fixed with explanation | "Fixed in `abc1234` - moved validation to middleware as suggested" |
| Needs discussion | "I see your point, but [reasoning]. What do you think about [alternative]?" |
| Won't fix (valid reason) | "Intentionally kept as-is because [reason]. The tradeoff is [explanation]." |
| Won't fix (out of scope) | "Good catch, but out of scope for this PR. Created #456 to track." |
| Question/clarification | "Good question - [explanation of why code works this way]" |

### Rules

1. **One commit per comment** - Makes it easy to trace what fixed what
2. **Always reply** - Never leave comments unaddressed
3. **Always resolve** - Clean up the conversation thread
4. **Reference commits** - Include SHA so reviewer can verify the fix
5. **Be respectful** - Even when disagreeing, explain your reasoning
6. **Create issues for scope creep** - If a comment suggests something bigger, create an issue instead