Ship Skill

Prepare to ship the current work by reviewing changes, creating a proper commit, and opening a pull request.

Phase 1: Review Changes

1. Read uncommitted files: Use git status and git diff to understand all changes
2. Provide a summary:
   • Summarize changes related to the current work session
   • Separately mention any unrelated changes
3. Wait for confirmation: Do not proceed until the user confirms

Phase 2: Ship (After Confirmation)

Branch Management

• If on main or master: Create a new branch named <type>/<short-description>
  • Examples: fix/null-pointer-auth, feat/user-export, chore/update-deps
  • The type should match the commit type you'll use
• If already on a feature branch: Stay on it

Staging

• Stage only files relevant to this task
• Unless the user instructs otherwise, exclude unrelated changes

Commit Creation

1. Draft the commit message following Conventional Commits:

   <type>[optional scope]: <ticket-number> <description>
   
   Issue: <concise issue description from session>
   Solution: <what was done and why, 2-5 lines>

2. Commit message format rules:

   • Header: <type>[optional scope]: <ticket-number> <description>
     • Type: feat, fix, docs, style, refactor, test, chore, build, or ci
     • Scope: Optional, indicates affected component (e.g., fix(auth):, feat(api):)
     • Description: Concise, imperative mood, no period at end
   • Body structure:
     • Issue: Include ticket number if mentioned in conversation, otherwise ask user
       • Examples: AIRC-17, AIAE-8, https://youtrack.jetbrains.com/issue/AIRC-19/...
       • If user declines to provide ticket, skip this line
       • If a ticket number was already established earlier in the session, reuse it for all subsequent commits related to the same task without asking again
       • After ticket number, add concise description of the issue from session prompts
     • Solution: Focus on explaining what problem is being solved, the reasoning and assumptions that were made (if any), and a high-level overview of the solution. This should be 2-5 lines max.
       • DO NOT list modified files or describe individual changes (visible from diff)
       • Focus on the "why" and high-level "what"

3. Create the commit using the message

PR Creation

1. Draft the PR body:

   • Title: Match the commit's short description
   • Body: Expand the Solution section with context for reviewers. Focus more on the intent, assumptions made during the conversation, and the reasoning behind the solution rather than listing changes
   • Include links to relevant tickets mentioned in the session

2. Write PR body to temporary file:

   mkdir -p .tmp
   echo "PR body" > .tmp/pr-body-file-name.md

   Use unique file names (e.g. with a timestamp or $RANDOM) to avoid conflicts with existing files.

3. Create the PR as a draft by default:

   gh pr create --draft --title "Title matching commit" --body-file .tmp/pr-body-file-name.md

   • Always use --draft unless the user has explicitly asked for an open (ready-for-review) PR.
   • Only drop --draft when the user clearly requested it (e.g. "open a PR", "create a non-draft PR", "mark it ready for review"). When in doubt, create a draft.

4. Show the PR link to the user when complete

PR updates

• If additional commits are made to the same branch, update the PR body and title when needed - to incorporate the new goals, assumptions, and changes. Do it only if the new changes affect the overall context or objectives.
• Always present the proposed changes in the title and the body of the PR to the user for confirmation before submitting updates to the PR.

Example Commit Message

feat(auth): add password reset flow

Issue: AIRC-42 Users unable to recover accounts when they forget passwords
Solution: Implemented email-based password reset with secure tokens. Users
receive a time-limited link, can set a new password, and are automatically
logged in. Tokens expire after 1 hour and are single-use to prevent abuse.

Example PR Body

Only the Summary section is required in the PR body. The rest is optional and should be included if it adds important context for reviewers.

## Summary

Adds password reset functionality using time-limited links to address user feedback about account recovery. Users can request a reset link via email, which contains a secure token. The link directs them to a page where they can set a new password. Tokens expire after 1 hour and are single-use to enhance security.

## Assumptions

- 1 hour link expiration was considered a good balance between usability and security - because users expect the email from the one hand, but from the other hand, they may not check their email immediately. 
- We decided to log users in automatically after they reset their password, because it provides a smoother experience and reduces friction, especially for users who may have trouble logging in after resetting.

## Changes

- Email-based reset flow with secure, time-limited tokens
- New `/reset-password` and `/reset-password/:token` routes
- Email templates for reset instructions
- Token expiration (1 hour) and single-use enforcement

## Explicitly left out of scope

- Social login options (e.g., Google, Facebook)
- Multi-factor authentication

## Related

- Issue: AIRC-42
- Design: [Figma link]