--- description: Generate a branch-aware commit message, commit staged changes, and sync epic/service docs --- You are an experienced software engineer generating clean, consistent git commit messages. Perform the following steps autonomously without asking the user for any input (except time spent and the commit message confirmation in Step 4a — never skip that one, per this repo's rule of never committing without asking). ## Step 1: Get branch info Run `git branch --show-current` to get the current branch name. Extract from the branch name: - **Card number**: e.g. `feature/RR-290-my-feature` → `RR-290` - **Branch type**: classify as one of: - `bugfix` — fixes broken or incorrect behavior - `feature` — adds new functionality - `hotfix` — urgent production fix - `chore` — maintenance, config, dependencies, refactoring ## Step 2: Get staged changes Run `git diff --staged` to get the staged changes. If there are no staged changes, stop and tell the user: "No staged changes found. Stage your changes with `git add` first." ## Step 3: Ask for time spent Ask the user: "How long did you spend on this? (e.g. 15m, 1h30m)" Wait for their response before proceeding. ## Step 4: Generate the commit message Using the branch info, staged diff, and time spent, generate a commit message following this exact format: ``` :()#time - bullet point describing what changed and why - bullet point describing what changed and why - bullet point describing what changed and why ``` This is the repo's **final** commit format. Emitting it directly (starting with `:`) is deliberate: the repo's `prepare-commit-msg` hook (`scripts/format-commit.js`) leaves any message that already begins with a type prefix untouched. Any other shape (e.g. ` #time ... : ...`) gets reprocessed by the hook, which double-stamps `#time` and drops the body. Rules: - Prefix: `:()#time ` with no space between `)` and `#time`. Use the full branch type verbatim (`feature`, `bugfix`, `hotfix`, `chore`) — do not abbreviate. - Title: concise, lowercase (except acronyms), no trailing period, max ~72 chars - Bullets: 3–6 maximum, focus on meaningful changes only, explain what AND why - Ignore formatting-only changes unless they affect behavior - Omit file names unless essential for clarity ## Step 4a: Confirm the message before committing Show the generated commit message once, in a fenced code block, exactly as it will be committed. Then ask: "Use this commit message? (yes / edit / no)" - **yes** → proceed to Step 5. - **edit** → ask what to change, regenerate the message incorporating that feedback, show the updated message in a fenced code block, and ask again. Repeat until the user says yes. - **no** → ask what's wrong with it (wrong focus, wrong type/card, too verbose, etc.), regenerate from scratch using that input, show it again, and ask again. Repeat until the user says yes. Do not run `git commit` until the user has explicitly said yes to a shown message. Do not show the message more than once per round — only re-show it after an edit/no round produces a new version. ## Step 5: Commit Run `git commit -m ""` using a heredoc to preserve formatting: ```bash git commit -m "$(cat <<'EOF' feature:(RR-290)#time 1h30m add equipment filter by status - added isValid filter parameter to equipment list API - updated repository query to conditionally apply status filter - ensures inactive equipment is excluded from client-facing results EOF )" ``` After committing, confirm briefly (e.g. "Committed.") — do not print or repeat the commit message again; it was already shown and approved in Step 4a. ## Step 6: Sync documentation The documentation lives in a **separate repo**, under `my-website/docs/`. It covers **both** the web-application and the backend, so this step is repo-aware. Its local path varies per machine, so resolve it before doing anything else in this step. ### 6a. Resolve the documentation repo path 1. Check whether `~/.claude/commit-msg-doc-repo-path` exists. 2. **If it exists**, read the path from it and verify with `test -d "/.git"` that it's still a valid git repo. If that check fails (moved, renamed, on a different machine), tell the user the saved path is no longer valid and fall through to step 3 as if it were missing. 3. **If it doesn't exist (first time this skill is used)**, ask the user: "What's the local path to the documentation repo?" Wait for their answer, expand `~` if given, and verify it with `test -d "/.git"`. If it's not a valid git repo, say so and ask again. Once valid, save it verbatim (no trailing slash) to `~/.claude/commit-msg-doc-repo-path` so future runs don't ask again. 4. Use this resolved path as `` everywhere below — do not hardcode any specific path. ### 6b. Detect which repo you are committing in Run `git rev-parse --show-toplevel` and take the basename: - **`pozytron-web-application`** → Frontend mode. - Source unit: an **epic** at `src/epics//` (camelCase, e.g. `contactManagement`). - Doc target: `/my-website/docs/Frontend-Docs/epics/.md` (one file per epic). - Global tree: `/my-website/docs/Frontend-Docs/folderStructure.md`. - **`pozytron-backend`** → Backend mode. - Source unit: a **service** at `services//` (kebab-case, e.g. `contact-request`). Endpoints are the serverless handlers under `services//src/handlers/` and `services//serverless.yml`. - Doc target: `/my-website/docs/Backend-Docs/.md` (one file per service). Backend-Docs currently holds only a placeholder `readme.md`, so most services will need their doc **created**. **Run this step whenever the staged changes from Step 2 touched the source unit for the detected repo** (`src/epics//` for frontend, `services//` for backend). If no source unit was touched at all, skip straight to Step 7. **Documentation-worthiness of _this commit's_ changes does NOT gate this step.** Even when the staged changes are trivial/formatting-only and add nothing new to document, you still MUST verify that the source unit's **already-implemented work as it stands today** is fully documented, and backfill anything missing. The reconciliation target is the epic/service's current state on disk — NOT the delta in this commit. In other words: touching the unit is the trigger to *audit and complete* its doc; you are never excused from that audit just because the current diff itself is not worth documenting. Only genuinely complete docs (already at full depth with no gaps) result in no edits here. ### Canonical frontend epic doc template Every frontend epic doc MUST follow the **full** structure below — this is the depth bar, modelled on `authentication.md` and `technicianManagement.md` (the gold-standard docs). A thin doc that only has frontmatter + intro + a flat `## Pages` list (as `contactManagement.md` was originally generated) is **incomplete** and must be brought up to this structure. Include every section that applies to the epic; omit a section only when the epic genuinely has no corresponding code (e.g. no `errors/` folder → no Error Handling section). 1. **Frontmatter** — `sidebar_position` (next available for a new doc; keep the existing value when editing). 2. **`# Title Case Name`** heading, followed by a one/two-sentence intro describing what the epic does. 3. **`## Overview`** — a lead-in sentence, then a bullet list of the epic's major flows/features as `- **Flow Name** - short description`. 4. **`## Directory Structure`** — a fenced code block showing the real `src/epics//` tree with an inline `# comment` per file/folder explaining its role. Reflect the **actual** folders on disk (`api/`, `errors/`, `hooks/`, `pages/`, `types/`, `constants/`, `utils/`). 5. **`## Pages`** — one `### Page Name` subsection per page, each with: the route, a fenced `tsx` snippet showing the import + `` (or the modal trigger), and a `**Features:**` bullet list of what the page does. 6. **`## Components Used`** — a Markdown table (`Component | Usage`) of the shared components the epic consumes, linking to Storybook docs where they exist (`[TextField](/docs/Storybook/textfield)`). 7. **`## Hooks`** — one `### hookName` subsection per hook, each with a fenced `tsx` snippet showing the destructured return value / call signature and a one-line description. 8. **`## API Endpoints`** — a Markdown table (`Endpoint | Method | Description`) of every endpoint the epic calls. 9. **`## Error Handling`** — the error codes/messages from `errors/`, shown as short fenced `tsx` excerpts. 10. **`## Localization`** — the key Polish (pl-PL) strings the epic surfaces. ### 6c. For each distinct source unit touched 1. **Match the doc file.** List the doc target directory and find the file for this unit. Match by closest existing filename — do NOT assume exact spelling; several frontend files are intentionally misspelled (`adminManagment.md`, `offerManagment.md`, `subscriptionManagment.md`). 2. **If the doc exists** — reconcile it against the repo: - Frontend: inspect the epic's actual folders (`pages/`, `hooks/`, `api/`, `types/`, `constants/`, `utils/`, `errors/`) and the concrete pages / flows / endpoints present. - Backend: inspect the service's `src/handlers/` (each handler ≈ one endpoint) and `serverless.yml` (HTTP method + path per function), plus `src/application`, `src/repositories`, `src/types`. - Read the existing doc to learn its exact format and voice. - **Frontend:** measure the existing doc against the **canonical frontend epic doc template** above. If it is missing whole sections (Overview, Directory Structure, per-page `### ` + Features, Components Used, Hooks, API Endpoints, Error Handling, Localization) — as a thin `## Pages`-only doc is — **upgrade it to the full structure**, populating the missing sections from the repo. If it is already at full depth, **fill gaps only** — add newly introduced pages/hooks/endpoints in the existing style and do not rewrite, reorder, or restyle content that is already correct. - **Backend:** ensure everything present in the service is documented; add any missing endpoints/flows matching the existing doc's style. Fill gaps only — do not restyle correct content. 3. **If the doc does NOT exist** — create it from scratch: - **Frontend:** follow the **canonical frontend epic doc template** above in full, using `authentication.md` as the reference for voice and formatting. - **Backend:** follow the format of a representative existing service doc — frontmatter with the next available `sidebar_position`, a `# Title Case Name` heading, a one/two-sentence intro, then `## Endpoints` (method, path, one-line purpose). 4. If a new source unit was introduced or the overall structure shifted, check whether the global overview needs updating (frontend: `folderStructure.md`) and apply it in the same tree style. 5. The documentation repo is a **separate git repo** — do not stage or commit it as part of the code commit. After editing, summarize what was added/changed and ask the user: "Documentation updated in the `documentation` repo. Commit those changes there too? (yes/no)". If **yes**, commit inside the documentation repo with a plain message like `docs: sync with changes` (that repo has no card-prefix format). If **no**, leave the edits unstaged for their review. ## Step 7: Ask about pushing Ask the user: "Would you like me to push the changes? (yes/no)" - If **yes** → run `git push` - If **no** → respond: "Done! Your changes are committed but not pushed."