prizmkit 1.1.111 → 1.1.112

package/bundled/skills/prizmkit-committer/SKILL.md

@@ -1,89 +1,101 @@
 ---
 name: "prizmkit-committer"
-description: "Pure git commit workflow with safety checks. Stages files, generates Conventional Commits message, and commits. Does NOT modify .prizmkit/prizm-docs/ — run /prizmkit-retrospective first. Trigger on: 'commit', 'submit', 'finish', 'done', 'ship it'. (project)"
+description: "Pure git commit workflow with safety checks. Stages intended files safely, generates a Conventional Commit message, commits, and verifies the result. Does not modify CHANGELOG.md or .prizmkit/prizm-docs/ by default; run /prizmkit-retrospective first only when the chosen lifecycle path requires docs sync. Trigger on: 'commit', 'submit', 'finish', 'done'. If the user says only 'ship it', clarify whether they mean commit or deploy. (project)"
 ---
 
 # PrizmKit Committer
 
 ### When to Use
-- User says "commit", "submit", "finish", "done with this task", "ship it"
-- After `/prizmkit-retrospective` has finished architecture sync
-- The UserPromptSubmit hook will remind to use this skill when commit intent is detected
+- User says "commit", "submit", "finish", "done with this task"
+- The current lifecycle path is ready to record changes in git
+- Required gates for the chosen path have passed or been explicitly deemed not applicable
 
 ### When NOT to Use
 - No uncommitted changes exist — nothing to commit
-- .prizmkit/prizm-docs/ not synced — run /prizmkit-retrospective first (full lifecycle only; the `plan → implement → committer` fast path skips this by design)
-- Code review not passed in pipeline mode — run /prizmkit-code-review first
-- Mid-merge conflict resolution — handle manually with git
+- User says only "ship it" — clarify commit vs deploy first
+- Current path still has required unresolved gates, such as failed tests, unresolved review findings, or required retrospective work
+- Mid-merge conflict resolution — handle conflicts manually before committing
 
-**PRECONDITION:**
+## Gate Policy
 
-| Required State | Check | If Missing |
-|---|---|---|
-| Uncommitted changes exist | `git status` shows modified/added/untracked files | Inform user "nothing to commit" and stop |
-| `.prizmkit/prizm-docs/` synced (feature/refactor) | `/prizmkit-retrospective` has run | Run `/prizmkit-retrospective` first |
-| Code review passed (pipeline mode) | `review-report.md` in artifact directory has `## Verdict: PASS` | Run `/prizmkit-code-review` first |
+`/prizmkit-committer` does not decide the entire lifecycle. It checks that the gates required by the chosen path are satisfied:
 
-> **Fast-path exemption**: the prizm-docs-synced and review-passed rows above gate the **full lifecycle**. Small, well-scoped changes using the `plan → implement → committer` fast path may commit without them — there is no retrospective or review-report artifact to check, so treat those rows as "satisfied when not applicable."
+| Path | Commit gate expectation |
+|---|---|
+| Direct edit | Verify the specific edit as appropriate; no spec/review/retro artifact required. |
+| Fast path | Simplified plan tasks complete; run tests or retrospective only if risk/knowledge triggers apply. |
+| Full path | Implementation complete; review passed; retrospective completed when docs or durable knowledge changed; tests completed when risk-triggered. |
 
-### Workflow
+If a gate is missing but not applicable, state why before committing. If a gate is missing and applicable, stop and run or request the missing gate.
 
-Follow these steps in order — skipping or reordering can stage sensitive files or commit without proper verification:
+## Workflow
+
+Follow these steps in order. The goal is to commit exactly the intended changes and avoid staging secrets or unrelated files.
+
+### Step 1: Status Check
 
-#### Step 1: Status Check
 ```bash
 git status
 ```
-- If "nothing to commit, working tree clean": inform user and stop
-- If there are changes: proceed
 
-#### Step 2: Generate Commit Message
-Analyze the staged diff and context (spec title, plan summary) to generate a concise Conventional Commits message. The message should capture the *what* and *why* of the change.
+- If the working tree is clean, inform the user and stop.
+- If changes exist, inspect modified, deleted, and untracked files before staging.
+- Warn about sensitive-looking files: `.env*`, `*credential*`, `*secret*`, `*.pem`, `*.key`.
+
+### Step 2: Generate Commit Message
+
+Analyze the staged/unstaged diff and task context to generate a concise Conventional Commit message:
+
+```bash
+<type>(<scope>): <description>
+```
 
-#### Step 3: Update CHANGELOG.md
-If CHANGELOG.md exists in the project root, append an entry following Keep a Changelog format under the `[Unreleased]` section. Match the existing style in the file.
+The message should capture what changed and why it matters.
 
-#### Step 4: Git Commit
+### Step 3: Stage Safely
 
-Stage changes using a safe strategy — **never use `git add .` or `git add -A`** as they may stage sensitive files (.env, credentials, secrets) or unintended changes:
+Never use `git add .` or `git add -A`; broad staging can accidentally include secrets or unrelated files.
 
-1. Review untracked files with `git status`. Warn the user if any files match sensitive patterns (`.env*`, `*credential*`, `*secret*`, `*.pem`, `*.key`).
-2. Stage tracked modified files: `git add -u`
-3. For new files: stage explicitly by name after confirming they should be included.
-4. Verify staged content with `git diff --cached --stat` before committing.
+1. Stage tracked modified/deleted files with `git add -u` when all tracked changes are intended.
+2. Stage new files explicitly by path after confirming they belong in the commit.
+3. Verify staged content:
 
 ```bash
-git commit -m "<type>(<scope>): <description>"
+git diff --cached --stat
 ```
-Follow Conventional Commits format.
 
-#### Step 5: Verification
+If staged content differs from the intended change set, unstage and correct it before committing.
+
+### Step 4: Commit
+
 ```bash
-git log -1 --stat
+git commit -m "<type>(<scope>): <description>"
 ```
-Confirm the commit was recorded.
 
-Then verify working tree is clean:
+Do not update `CHANGELOG.md` by default. Changelog updates belong to release, publish, version-bump workflows, or explicit user requests.
+
+### Step 5: Verification
+
 ```bash
+git log -1 --stat
 git status
 ```
-- If "nothing to commit, working tree clean": commit verified successfully, proceed
 
-#### Step 6: Optional Push
+Confirm the commit was recorded and report whether the working tree is clean or has remaining intentionally uncommitted changes.
+
+### Step 6: Optional Push
+
 Ask user: "Push to remote?"
-- Yes: `git push`
-- No: Stop
 
-**Headless mode**: If the skill was invoked with `--headless` in the args (e.g., `/prizmkit-committer --headless feat(F-001): ...`), **SKIP this step entirely**. Do NOT ask the question. Do NOT push. Stop after Step 5 verification. Headless mode is used by autonomous pipeline sessions where there is no human to answer interactive prompts.
+- Yes: run `git push`
+- No: stop after reporting the commit hash
 
-## Example
+**Headless mode**: If invoked with `--headless`, skip the push question, do not push, and stop after Step 5 verification.
 
-**Feature commit:**
-```
-git commit -m "feat(avatar): add user avatar upload with S3 storage"
-```
+## Examples
 
-**Bug fix commit:**
-```
+```bash
+git commit -m "feat(avatar): add user avatar upload with S3 storage"
 git commit -m "fix(auth): handle null token in refresh flow"
+git commit -m "docs(prizm): clarify lifecycle gate policy"
 ```