| name | gini-fix |
| description | Diagnose and fix a non-trivial bug ticket - reproduce it, find the root cause, write the diagnosis to specs/, then implement the fix with a regression test. Pass the ticket id as argument (e.g. PP-1234, IPC-42 - any board). |
You are diagnosing and fixing bug ticket $ARGUMENTS. Root cause comes before
any fix: no code change until the diagnosis is written down and confirmed.
Never fix a symptom whose cause you haven't found.
0. Load platform conventions — REQUIRED FIRST
Read platform.md in this skill's directory. It defines how to reproduce
bugs in this repository (apps, build variants, logging), how to run tests,
how to verify, and the commit conventions. Every platform-specific decision
below MUST come from that file, never from your own defaults. If the file is
missing, stop and tell the user this repository is not set up for the shared
fix workflow.
1. Fetch the ticket
Fetch $ARGUMENTS from Jira (any board — PP or otherwise). Read the summary,
description, comments, and linked issues, and mine them for: observed vs.
expected behavior, stack traces or logs, affected SDK/app versions, device or
OS specifics, and reproduction hints. If the ticket cannot be fetched, ask
the user to paste its content instead of guessing.
2. Reproduce the bug
Reproduce it the way platform.md prescribes — prefer the cheapest faithful
reproduction (a failing unit test beats launching an app). If you cannot
reproduce it, do NOT start changing code on speculation: report what you
tried and ask the user (via AskUserQuestion) for the missing detail —
exact version, configuration, input document, locale, and so on.
3. Find the root cause
Run a disciplined hypothesis loop:
- Form an explicit hypothesis about the cause; state it before testing it.
- Gather evidence: read the involved code, follow the data flow, check the
git history of the suspicious lines (when did this last work?), add a
narrowing test or targeted logging where
platform.md suggests.
- Reject or confirm, then iterate. Keep going until you can name the root
cause at file-and-line precision and explain the mechanism from cause to
observed symptom.
- Distinguish the root cause from where the symptom surfaces — they are
usually in different places. Fixing at the symptom site needs explicit
justification.
4. Write the diagnosis
Write specs/$ARGUMENTS-bug.md (create specs/ if needed):
# <Ticket ID>: <Title>
Status: draft
Ticket: <link to the Jira ticket>
## Symptom
Observed vs. expected behavior, in your own words.
## Reproduction
Exact steps or the failing test that demonstrates the bug.
## Root cause
The defect and its mechanism, referencing code with file paths and lines.
How the cause produces the symptom.
## Proposed fix
What changes and where. Minimal — no drive-by refactoring. Note public API
impact (should normally be "none" for a bug fix).
## Regression test plan
The test(s) that fail before the fix and pass after, their location, and the
test stack to use (match neighboring tests — see platform.md).
## Out of scope
Related issues noticed but deliberately not fixed here (file tickets instead).
## Open questions
Anything still unresolved.
5. Checkpoint — confirm before fixing
Show the user the root cause and proposed fix (via AskUserQuestion). They can:
- confirm — continue to step 6 in this session, or
- stop here — the diagnosis file stands on its own; the fix can be
implemented later with
/gini-build $ARGUMENTS in a fresh session.
Do not proceed to code changes without confirmation.
6. Implement the fix, regression test first
- Write the regression test first and run it: it MUST fail for the reason
the diagnosis describes. A regression test that passes before the fix
proves nothing — rework it until it fails correctly.
- Apply the minimal fix from the diagnosis. Match the style of the file you
touch. No opportunistic refactoring, no scope creep into "Out of scope".
- Re-run the regression test (now passing) and the tests around the touched
code.
7. Verify
Run the verification steps defined in platform.md for the affected modules,
and re-check the original reproduction from step 2 no longer occurs. Fix what
fails and re-run until clean. Report results honestly — if something still
fails or was skipped, say so explicitly.
8. Wrap up
- Update the diagnosis file's
Status: line from draft to fixed.
- Summarize for the user: root cause, the fix (file paths), the regression
test, verification results, and anything left to manual QA.
- Offer to commit following the commit conventions in
platform.md, but do
not commit or push unless the user asks.
