Skip to content

Commit a92db8c

Browse files
vpomerleauvpomerleau
authored
Merge pull request #20295 from mozilla/claude-code-dx-improvements
chore(claude): add skills, improve CLAUDE.md, fix VS Code config
2 parents 6bbc2d1 + c8908a3 commit a92db8c

4 files changed

Lines changed: 178 additions & 1 deletion

File tree

‎.claude/skills/fxa-jira-bug-description/SKILL.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
name: fxa-jira-bug-description
3+
description: Drafts a Jira bug report for an FXA issue. Gathers repro steps, expected vs actual behaviour, and affected surface, then outputs a structured report ready to file or hand to Claude for investigation.
4+
user-invocable: true
5+
---
6+
7+
# FXA Jira Bug Report
8+
9+
Draft a Jira bug report for an FXA issue. Output the description only — do not create, edit, or suggest changes to any source files.
10+
11+
## Step 1: Gather Context
12+
13+
If a Sentry link, error log, or stack trace was provided, read it first and infer as much as possible before asking anything.
14+
15+
Required information:
16+
- **What:** One-sentence description of the bug
17+
- **Steps to reproduce:** Numbered steps from a known starting state
18+
- **Expected behaviour:** What should happen
19+
- **Actual behaviour:** What actually happens
20+
- **Affected surface:** Which flow, page, or API endpoint; which users or account states are affected
21+
22+
Also useful — ask only for what is missing:
23+
- Error message, Sentry event, or stack trace
24+
- Browser, OS, or environment (if frontend)
25+
- Account state at time of bug (e.g. 2FA enabled, passwordless, linked account)
26+
- Severity — data loss, security impact, broken flow, visual/cosmetic
27+
28+
If all required information is clear, proceed directly to Step 2.
29+
30+
## Step 2: Research
31+
32+
Search only the packages likely involved. Find:
33+
- The code path most likely responsible (route handler, component, service method)
34+
- Any recent changes to that path (`git log` on the relevant files)
35+
- Whether a similar bug has been fixed before (look for related test cases or comments)
36+
37+
Incorporate findings directly into Root Cause and Key Reference Files. Surface genuine unknowns as Open Questions.
38+
39+
## Step 3: Output
40+
41+
**Summary:** `[area] <concise bug description>` — e.g. `[auth] Passkey registration fails silently when device has no authenticator`
42+
43+
**Background:**
44+
What the bug is, where it occurs, and who is affected. 2–3 sentences.
45+
46+
**Steps to Reproduce:**
47+
Numbered steps from a known starting state. Include account state and environment where relevant.
48+
49+
**Expected Behaviour:**
50+
What should happen.
51+
52+
**Actual Behaviour:**
53+
What actually happens. Include error message, code, or Sentry event if available.
54+
55+
**Affected Surface:**
56+
Which users, flows, account states, browsers, or environments are affected. Note if intermittent.
57+
58+
**Severity:** *(Critical / High / Medium / Low)*
59+
- Critical — data loss, security vulnerability, auth bypass
60+
- High — broken core flow affecting multiple users
61+
- Medium — degraded experience, workaround exists
62+
- Low — cosmetic, edge case, minor inconvenience
63+
64+
**Root Cause:** *(if known or suspected — omit if unknown)*
65+
Where in the code the bug originates. Reference specific file and function if identified.
66+
67+
**Acceptance Criteria:**
68+
- Bug is no longer reproducible following the steps above
69+
- Regression test added covering the broken path
70+
- *(add any additional observable outcomes)*
71+
72+
**Key Reference Files:**
73+
Specific files relevant to investigation or fix. One line each.
74+
75+
**Out of Scope:** *(omit if not needed)*
76+
77+
**Open Questions:** *(omit if none)*
78+
79+
## Guidelines
80+
81+
- Output the description only — no source file changes
82+
- Steps to Reproduce must be precise enough for another engineer to reproduce independently
83+
- Do not speculate on root cause unless there is clear evidence — use Open Questions instead
84+
- Severity should reflect user impact, not code complexity
85+
- Always include a regression test in Acceptance Criteria
86+
- If the bug has security implications (auth bypass, data exposure, token leakage), flag severity as Critical and note it explicitly in Background

‎.claude/skills/fxa-jira-feature-description/SKILL.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
name: fxa-jira-feature-description
3+
description: Drafts a concise Jira description for an FXA task. Gathers context via targeted interview, researches relevant patterns in the repo, then outputs a clean description ready for an engineer to hand to Claude for implementation.
4+
user-invocable: true
5+
---
6+
7+
# FXA Jira Description
8+
9+
Draft a Jira description for an FXA task. Output the description only — do not create, edit, or suggest changes to any source files.
10+
11+
## Step 1: Gather Context
12+
13+
If a planning doc, epic description, or tech spec was provided, read it first and infer what, why, packages, and constraints before asking anything.
14+
15+
Required information:
16+
- **What:** What is being built or changed, in one sentence
17+
- **Why:** Motivation — user need, requirement, bug, or tech debt
18+
- **Packages:** Which specific package(s) will be modified (e.g. `fxa-auth-server`, `libs/accounts/passkey`)
19+
- **Constraints:** Feature flag, breaking change, migration, L10n — or none
20+
21+
If all four are clear from provided context, proceed directly to Step 2. Otherwise ask for only what is missing in a single message. Also invite related PRs, tickets, existing approach notes, design mockups, or flow diagrams that would add useful context.
22+
23+
## Step 2: Research
24+
25+
Search only the packages identified in Step 1. Find the most relevant existing patterns: similar feature, nearby route, equivalent component. Expand to the broader repo only if nothing relevant is found there.
26+
27+
Identify:
28+
- Key files an implementer will need to touch
29+
- The closest existing reference implementation to follow
30+
- Whether tests, metrics, or security events apply (see Step 3)
31+
32+
Incorporate findings directly into the draft — do not list them separately or ask for confirmation. Surface genuine blockers as Open Questions.
33+
34+
## Step 3: Output
35+
36+
**Design:** *(Figma link if applicable. Note that all copy, strings, and visual specs should be taken from the latest Figma file — do not reproduce design details here as they may change before implementation. Omit if no design involved.)*
37+
38+
**Background:**
39+
Why this is needed and what it enables. 2–4 sentences.
40+
41+
**Acceptance Criteria:**
42+
Observable, testable outcomes. Each item verifiable without reading the code. Include criteria for tests, metrics emission, and security events where applicable to this task.
43+
44+
**Implementation Steps:**
45+
Numbered steps with file paths, method names, and structural guidance. Reference the nearest existing pattern for each step. No code snippets — file locations, types, and patterns only.
46+
47+
**Tests:**
48+
What needs to be tested. Unit, integration, and snapshot coverage expectations. Reference the nearest existing test file as a pattern. Omit if covered inline above.
49+
50+
**Metrics & Security Events:** *(omit if not applicable)*
51+
Any StatsD metrics or security events (`log.info`, `request.emitMetricsEvent`, `customs` checks) that should be emitted. Reference the nearest equivalent for naming conventions.
52+
53+
**Key Reference Files:**
54+
Specific files the implementer should read before starting. One line each.
55+
56+
**Out of Scope:** *(omit if not needed)*
57+
58+
**Open Questions:** *(omit if none)*
59+
60+
## Guidelines
61+
62+
- Output the description only — no source file changes
63+
- Implementation Steps should give enough detail to start work without follow-up questions — file paths and patterns, not prose
64+
- Do not include design details (copy, colours, layout, component specifics) — note that the implementer should refer to the latest Figma file
65+
- Omit redundant or obvious acceptance criteria
66+
- Include Tests, Metrics & Security Events sections only when relevant to the task type
67+
- If motivation or scope remain unclear after asking, flag as an Open Question rather than assuming

‎.vscode/settings.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@
2525
"typescript.tsdk": "node_modules/typescript/lib",
2626
"files.exclude": {
2727
".nx": true,
28-
".claude": true,
2928
"**/.git": true,
3029
"**/.DS_Store": true,
3130
"**/Thumbs.db": true,

‎CLAUDE.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Security takes **absolute precedence**. This repository handles Mozilla authenti
66

77
- Operate strictly under `<FXA_REPO_ROOT>`; normalize paths; do not follow symlinks outside the repo.
88
- **Writes allowed** to working tree; always present a diff for review **before** any staging/commit.
9+
- Do not modify files adjacent to the requested change; mention issues found but do not fix them.
910
- **Ask first** for any command (build/test/install, DB ops, git, services). Do **not** run `git add/commit/push/rebase` unless explicitly told to.
1011

1112
## 2) Non-Negotiables
@@ -76,3 +77,27 @@ _Note:_ This is a general overview and may vary per library/package. For authori
7677
**Never edit existing published migration files.**
7778

7879
> When asked, show the exact minimal command block you intend to run; wait for approval.
80+
81+
## 6) Git Commit Messages
82+
83+
Follow the commit message format defined in [CONTRIBUTING.md — Git Commit Guidelines](https://github.com/mozilla/fxa/blob/main/CONTRIBUTING.md#git-commit-guidelines) and the `~/.gitmessage` template configured globally.
84+
85+
Key points: `type(scope): subject` format; imperative present tense subject; `Because:` / `This commit:` body sections; `Fixes #N` footer for issues.
86+
87+
## 7) Available Skills
88+
89+
Suggest these proactively when the task matches — do not wait to be asked.
90+
91+
| Skill | Use when |
92+
| ------------------------------- | ------------------------------------------------------------------------------------------- |
93+
| `/fxa-review` | Before merging — thorough parallel review covering security, TS, logic, tests, architecture |
94+
| `/fxa-review-quick` | Quick pre-merge check, single pass, no subagents |
95+
| `/fxa-security-review` | Landing auth, session, crypto, or payment changes |
96+
| `/fxa-jira-feature-description` | Writing a Jira description for a new feature or enhancement |
97+
| `/fxa-jira-bug-description` | Filing a bug report |
98+
| `/fxa-check-smells` | Suspecting code quality issues in changed files |
99+
| `/fxa-check-react` | Reviewing React/TSX component changes |
100+
| `/fxa-check-docs` | Improving docs, JSDoc, or README in changed files |
101+
| `/fxa-explain-code` | Understanding what changed and why |
102+
| `/fxa-simplify` | Cleaning up recently written code |
103+
| `/fxa-check-githistory` | Checking for regressions or conflicts with past fixes |

0 commit comments

Comments
 (0)