Commit to Graphite Stack

Commit to Graphite Stack

Creates a thoughtful commit in a Graphite stack by analyzing staged changes, crafting a descriptive message, and using gt create.

⚠️ MANUAL ONLY — This skill runs ONLY when you explicitly ask to commit. It will never auto-trigger.

Arguments

Arg	Required	Description
context	No	Extra context about the change — e.g. the reason, motivation, or any details to weave into the commit message body.

Workflow

Analyze Staged Changes

• Run git diff --cached --stat to see what's staged
• If nothing is staged, inform the user and suggest they stage files with git add before retrying
• Review the actual changes to understand the scope
• Identify the primary feature or fix being committed

Check PR Size

• Count the lines changed (insertions + deletions) excluding test files (*.spec.*, *.test.*) and lock files (pnpm-lock.yaml, package-lock.json, yarn.lock)
• Use: git diff --cached --stat -- . ':!*.spec.*' ':!*.test.*' ':!pnpm-lock.yaml' ':!package-lock.json' ':!yarn.lock' and read the summary line
• If the total exceeds 400 lines, warn the user:
  • Display the line count (with and without excluded files)
  • Suggest splitting into smaller, focused commits for easier review
  • Ask whether to proceed anyway or abort so they can split the work
• If the user chooses to proceed, continue normally

Extract Linear Ticket Number

• Present the user with these options:
  1. Enter a ticket number — provide an existing Linear ticket ID to associate with this commit
  2. Create a new ticket — create a Linear ticket based on the staged changes (use the linear-ticket-create skill, deriving the title and description from the diff context), then use the newly created ticket ID
  3. Skip ticket — proceed without a ticket prefix (not recommended for feature work)
• The ticket prefix goes at the start of the title line: [FTF-123] feat: add user authentication

Choose Branch Name

• Ask the user: "What should the branch be?"
• Present two options:
  1. Type a name — the user provides a branch name directly
  2. Auto-generate — derive a branch name from the ticket and commit summary (e.g. feat/add-user-auth or ftf-123/add-user-auth)
• The chosen name is passed as the positional arg to gt create <name> -m "message"

Craft Commit Message

• Follow conventional commits format: [TICKET] <type>: <description> (ticket prefix from previous step)
• Types: feat, fix, refactor, docs, test, chore, perf, ci
• Start with a concise one-line summary
• Add bullet points describing the key changes made (what was added/removed/changed, not implementation details)
• If a context argument was provided, incorporate it naturally into the summary and/or bullet points (e.g. motivation, business reason, linked requirement)
• Keep it focused on the single responsibility principle

Present Summary for Review

• Display the commit message in a clear, readable format
• Show the file count and insertion/deletion stats
• List the key files being modified/added
• Ask user for explicit approval before proceeding

Commit with Graphite

• Only proceed after user approval
• Use gt create <branch-name> -m "message" (branch name from the earlier step)
• Pass message via heredoc for multiline commits
• Verify output shows expected files

Conventional Commits Examples

Feature

[FTF-123] feat: add user authentication

Summary
Adds JWT-based authentication with login endpoint and route protection.

Implement JWT token generation and login endpoint with credentials validation.
Store hashed passwords in database.
Add auth middleware for protected routes.

Test plan

- [ ] Log in with valid credentials and confirm token is issued
- [ ] Verify protected routes reject unauthenticated requests

Bug Fix

[FTF-456] fix: resolve memory leak in cache cleanup

Summary
Fixes event listener leak causing memory growth in long-running sessions.

Fix improper cleanup of event listeners.
Add proper disposal in component lifecycle.
Verify memory usage with profiler.

Test plan

- [ ] Run app for 10+ minutes and confirm stable memory usage via profiler
- [ ] Verify no dangling event listeners in component teardown

Refactor

[FTF-789] refactor: simplify state management

Summary
Consolidates state logic into a single reducer module with stricter types.

Extract reducer logic into separate module.
Remove redundant state variables.
Improve type safety with discriminated unions.

Test plan

- [ ] Verify all state transitions still work
- [ ] Confirm no regressions in UI behaviour

Approval Step

Before creating the commit, present a summary:

📋 COMMIT SUMMARY
─────────────────────────────────────────
Ticket: FTF-42
Type: feat
Title: [FTF-42] feat: add weekly prize modals and gift box icons

Files Changed: 14 files
+ 649 insertions, - 10 deletions

Key Files:
  ✨ src/lib/components/WeeklyWinModal.svelte
  ✨ src/lib/components/WeeklyNoWinModal.svelte
  ✨ src/lib/components/ui/gift-icon/gift-box-closed.svelte
  ✨ src/lib/components/ui/gift-icon/gift-box-open.svelte
  📝 src/lib/state.svelte.ts
  📝 src/routes/+page.svelte

PR Description:
  Summary
  Adds weekly prize outcome modals and gift box icon components.

  Add WeeklyWinModal and WeeklyNoWinModal components for prize outcomes.
  Add gift-box-closed and gift-box-open icon components.
  Export new icons from gift-icon module.
  Update state management for weekly prize flow.
  Integrate new components into main page.

  Test plan

  - [ ] Open the weekly prize flow and verify win modal displays on win
  - [ ] Verify no-win modal displays on loss
  - [ ] Confirm gift box icons render correctly

Ready to commit? (yes/no)

Only proceed with gt create if user confirms. If user declines, ask what they'd like to change (message wording, scope, split into multiple commits, etc.) and revise accordingly.

Key Principles

• One responsibility per commit - Each commit should be independently reviewable
• Descriptive over brief - "add authentication" > "update code"
• Title captures intent, bullets capture scope - The one-line summary explains why; bullet points list what was added/removed/changed
• Stacked PRs benefit - Good commits make smaller, focused PRs easier to review
• User approval required - Always show summary and wait for confirmation before committing

When to Use

ONLY when you explicitly ask to commit.

This skill is manual and does not auto-trigger. Examples of explicit requests:

• "commit these changes to the graphite stack"
• "create a commit with the staged changes"
• "gt commit with a good message"
• Any variation that clearly indicates you want to create a commit

This skill will NEVER run unless you explicitly invoke it or ask for a commit.

PR Description Style

Graphite uses the commit body as the PR description. The commit message passed to gt create -m MUST use this format so PRs have proper descriptions:

[TICKET] <type>: <concise title>

Summary
<One-sentence overview of what the PR adds/changes/removes.>

<Bullet points expanding on specific changes — what was added, removed, or restructured.>

Test plan

- [ ] <Verification step 1>
- [ ] <Verification step 2 (if needed)>

The Stack / Base section is added automatically by Graphite — do NOT include it in the commit message.

PR Description Examples

[FTF-101] feat: add closing legal sections and signature block to agent PDF

Summary
Adds the closing legal sections and a signature block to the agent PDF.

Adds sections 11 (Terms and Conditions), 12 (Consent by the Agency) and 13 (Acceptance by the Discountor).

Adds a discountee signature block via buildAgentSignatureSection.

Test plan

- [ ] Export an agent deal PDF
- [ ] Confirm sections 11-13 render correctly
- [ ] Confirm the signature block renders

[FTF-102] feat: add discountor header to agent and mortgage PDFs

Summary
Adds the discountor header to the agent and mortgage PDFs and drops the redundant summary line.

Adds a "1. THE DISCOUNTOR" header (FT FINANCE (PTY) LTD) to the agent and mortgage layouts.

Removes the global "1. THE DISCOUNTEE" summary line from buildDealHtml now that each layout has its own discountee section.

Test plan

- [ ] Export an agent deal PDF and confirm the discountor header appears
- [ ] Export a mortgage deal PDF and confirm the discountor header appears
- [ ] Verify the old summary line is gone from both

[FTF-103] refactor: restructure seller PDF with discountor header and signatures

Summary
Restructures the seller PDF with a discountor header, property description and signatures.

Adds a "1. THE DISCOUNTOR" header (FT FINANCE (PTY) LTD).

Replaces the discountee banking-details block with a PROPERTY DESCRIPTION section.

Removes the "MAX ADVANCE (80%)" row and reflows the rate / deeds-search rows.

Adds a TERMS AND CONDITIONS clause and per-applicant signature blocks.

Minor signature-layout tweaks to the undertaking-request template.

Test plan

- [ ] Export a seller deal PDF
- [ ] Confirm the discountor header renders
- [ ] Confirm the property description section renders
- [ ] Confirm terms and signature blocks render

Integration with Graphite

This skill pairs with Graphite's stacking workflow:

1. Create a commit with gt create
2. Make another change, create another commit with gt create
3. Run gt submit --no-interactive to push entire stack to PR

Each well-crafted commit becomes a reviewable unit in the stack.