agentic-auto-improve

Move a contract forward by exactly one step. Asks the script what the next move is, then takes it: start the sub-tasks that are ready, escalate a failure to the architect, hand a finished contract to verification, or report what is blocked and why. Makes one move and stops, because a merge-gated loop suspends until somebody merges and /pr-merged wakes it. Use when: user says /advance, 'what is next on this contract', 'start the next sub-task', 'continue the contract', or after /pr-merged reports newly released sub-tasks. Never iterates on its own.

Read-only inspector for the contract-critic accuracy-skip system. Prints the per-area clean_streak, skip_eligible flag, and recent history. Use when: user says /contract-accuracy, 'show accuracy', 'which areas can skip critic', 'why did /design-first skip the critic on X', or wants to audit the system before tuning area-mapping.json.

Manually run contract-critic against an already-approved (or skipped) contract. Use when: user says /critique-now <path>, 'run critic anyway', 'audit this contract', 'I want a second opinion on this approved design', or wants to verify the accuracy-skip system was right to skip a previous contract.

Run the cross-area scanner against a concept contract or a list of files and print the top-3 adjacent areas with score breakdowns. Use when: the user types `/cross-impact <contract-path>` or `/cross-impact <comma-separated-files>`, or asks "what other areas would this contract affect?", "what's adjacent to this set of files?", or "before I run /design-first, what would this touch?". This is the user-invocable wrapper around `.claude/scripts/cross_area_scan.py`. The same script is invoked by `data-architect` Step 4.5 automatically; this skill is the manual exploration path.

Systematic 4-phase debugging protocol — REPRODUCE → ISOLATE → HYPOTHESIZE → VERIFY before any fix is written. Forces root-cause analysis instead of symptom patching. Writes findings to .claude/debug-notes-<slug>.md. Use when: user says /debug, 'debug this', 'why is X failing', 'fix this bug', or when a symptom is reported. Mandatory for bugs under any root named by the safety-critical.roots, auth.roots or migration.root slots of .claude/project-profile.md. Produces a HANDOFF suitable for dotnet-backend-architect or angular-senior-dev to implement the fix.

Kick off the Data-First Engineering Protocol for any non-trivial task. Classifies the task, invokes the data-architect to produce a concept contract at .claude/concepts/, resolves Open Questions with the user, and hands off to implementer agents with the contract as their authoritative input. Use when: user says /design-first, 'design this feature', 'start a new feature', or is about to request any non-trivial implementation. The concept-gate.py hook will block Edit/Write without an approved contract, so this skill is the entry point.

Run the whole contract-driven delivery chain end to end in one invocation: intake, design contract, test-first implementation, adversarial review, verification, commit and pull request. Drives the working agent chain (/task, /design-first, /tdd-first, the reviewer agents, /verify-before-done, /git-commit, /ship) and pauses only at the gates a human must answer. Use when: user says /flow, 'run the whole flow', 'take this all the way to a PR', 'do the full autonomous flow', 'end to end', or hands over a request and expects a pull request back rather than a plan. Replaces the Contract Orchestrator scripts, which were removed; see the section at the end.

Commit staged changes safely. Runs /verify-before-done first, lets the user choose which files to stage, drafts a project-style commit message (subject + Files / Verification / Contract / Status sections + Co-Authored-By trailer), and commits via HEREDOC. Halts on verification failure, suspected secrets, or pre-commit hook errors. Never uses --no-verify or --amend without explicit user request. Use when the user says /git-commit, 'commit this', 'make a commit', or after a feature is implementation-complete.

Append a lesson-learned entry to .claude/registries/JOURNAL.md. Use when: the user says /journal-add, 'log a lesson', 'add to the journal', 'record this for next time', or after a production incident / debugging session / contract review surfaces a non-obvious insight that future contracts should heed. The journal is read by data-architect (Step 1) and contract-critic on every run.

Show every concept contract under .claude/concepts/ grouped by project and status. Highlights contracts needing user action (drafts with unresolved Open Questions, approved contracts not yet implemented). Use when: user says /list-contracts, 'show my contracts', 'what's pending', or after finishing a feature to see what's next.

Capture an aspirational direction-setting thought as a north-star file at .claude/north-stars/<YYYY-MM-DD>-<slug>.md. North-stars are the WHAT-WE-WANT register; distinct from JOURNAL.md (lessons from what already happened) and contracts (concrete tasks). Read by data-architect Step 0.5 on every /design-first and reviewed via /north-star-review to emit ranked suggestions of contracts that would move the codebase toward the aspiration. Use when: the user types `/north-star "<aspiration>"`, or says "capture this as a goal", "record this direction", "I want the system to eventually X", or describes a future-state intent that should influence design decisions beyond the current task.

Run the north-star review engine against every active thought in the project. The engine reads each thought's anti-patterns, greps the live codebase for hits, and emits a ranked list of suggested next-step contracts. Optionally updates the `Current gap` and `Suggested next steps` sections of each thought file in place. Use when: the user types `/north-star-review`, "what should we work on next", "review my goals", "show me how the codebase aligns with my aspirations", or wants a weekly/monthly check-in on long-horizon direction.

Question-quality rubric for AskUserQuestion calls during /plan mode. Triggers when the developer says /plan-questions, "ask better questions", "that question was confusing", or as a mid-session reset. Auto-injected by ~/.claude/hooks/plan-question-advisor.py whenever plan mode is detected.

The closing phase of one sub-task: once its pull request has merged, record the completion and work out which pending sub-tasks that releases. Verifies the merge by asking GitHub rather than trusting the claim, writes a completion record stamped verified: github, recomputes the released set, and hands that set back to its caller. Iteration belongs to /advance, not to this phase. Use when: the loop closes a sub-task, or a person says /pr-merged, 'PR 40 is merged', 'these PRs merged, continue', or returns after merging work outside a running loop. Reads a contract handoff plan and writes the result and state stores.

Promote a recurring UI mistake from JOURNAL.md into an automated guard rule in architecture-guard.rules.json. The promotion is gated: requires 3+ journal entries tagged `ui-evolution + recurring-mistake` matching the same pattern. Use when: the user says `/promote-ui-rule`, "promote this UI rule", "the designer keeps catching X, automate the check", or after a code review surfaces the third occurrence of the same UI anti-pattern.

Turn a finished work item into a pull request that GitHub actually links back to its issue. Reads the Work Item Brief for the branch, worktree, contract and issue id, runs /verify-before-done, composes the PR title from the modules the diff really touches, pushes from the tree that holds the commits, opens the PR, then verifies the Closing Link with verify_issue_link.py and performs at most ONE repair. Writes pr:, issue_link: and status: shipped back into the brief. Use when: user says /ship, 'open the PR', 'ship it', 'raise a pull request', or after /verify-before-done passes on a completed item. This is the last stage of the delivery chain.

Inject SQL Server schema-design knowledge into a task before the schema is written — partitioning, hierarchy modelling, SARGability, compression and temporal tables — by routing to .claude/templates/tsql-patterns.md rather than restating it. Distinct from migration-safety-reviewer (will this migration run cleanly on existing data?) and sql-performance-reviewer (is this existing query fast?): this one decides the SHAPE. Use when: user says /sql-server-patterns, asks how to model or index a table, proposes partitioning or a hierarchy, or when data-architect is designing persistence and dotnet-backend-architect is about to write an entity, configuration or migration.

Intake a work item — a GitHub issue (this project's tracker), or a Jira/ADO item, or a free-text request — and turn it into a normalized Work Item Brief at .claude/work-items/, with acceptance criteria, size classification, an issue-linked branch, and optionally an isolated parallel worktree branched from master. Resolves ambiguity with the user BEFORE any design happens, grades the item against the active north-stars at .claude/north-stars/ (capturing a new one via /north-star when the intake text carries an aspiration), then runs /design-first automatically in the same turn — the handoff is pre-authorized by the /task invocation, not a question to put to the user. Use when: user says /task, '/task #123', 'start on this issue', 'pick up issue 42', 'work on this in a worktree', pastes a GitHub issue URL, or begins any piece of tracked work. This is the front door of the delivery chain.

Enforce a RED→GREEN→REFACTOR cycle for a feature. Writes failing tests BEFORE implementation, runs the test suite to confirm the red state, then invokes the implementer agent with the failing tests as authoritative input, then re-runs to confirm green. Use when: user says /tdd-first, 'do this test-first', 'TDD this feature', or before any safety-critical / migration / auth path change. Default for changes under any root named by the safety-critical.roots slot of .claude/project-profile.md, and anything touching a live external-action path.

Scan .claude/registries/MECHANISMS.md and .claude/registries/VOCABULARY.md for dead file references. Reports any backticked path entries whose files no longer exist. Use to prevent the reusable mechanism registry from rotting when files are renamed or deleted. Use when: user says /validate-registries, 'check the registry', 'find dead links in MECHANISMS', or as a weekly sanity check.

Run the verification gauntlet before claiming a task is complete. Executes build, tests, migration check, generated-model drift check, and HANDOFF completeness check. Blocks on any failure. Use when: an agent or the user is about to declare Status=complete, before committing, before opening a PR, or whenever the phrase 'done', 'complete', 'ready to ship', 'finished' is used. Mandatory final step in /tdd-first and recommended final step in /design-first.