nudge

name	nudge
description	Use for Nudge hook feedback and repo Nudge setup, `.nudge` rules, validation, CI, and rule debugging.

Nudge

Purpose

Nudge is a collaborative memory layer for agent hooks. This skill is the router: pick the focused reference for the Nudge situation, follow it, then return to the user's task.

When to use

• Nudge blocks, warns about, or substitutes a tool command.
• Nudge surfaces learned repo context; use nudge-learnings for the focused debugging-memory workflow.
• The user asks what Nudge is or why it interrupted.
• The user asks to install Nudge locally or set up hooks for a repo with Nudge rules.
• The user asks to configure, validate, check, write, debug, or update Nudge rules or learned incident notes.
• The user asks to add Nudge to CI, pre-commit, or another scripted gate.
• You find .nudge.yaml, .nudge.yml, or .nudge/ while working.

Workflow

1. Read the Nudge output or user request closely.
2. Choose the most specific reference:
   • Hook responses, interrupts, warnings, substitutions, provider support: references/hook-responses.md
   • Local installation, hook setup, teammate cloned repo bootstrap: references/setup.md
   • Writing new rules: references/rule-writing.md
   • Noisy, silent, or surprising rules: references/rule-debugging.md
   • Validation commands and check selection: references/validation.md
   • CI, pre-commit, release gates, or scripts: references/ci.md
   • Learned incident notes and proactive debugging memory: use nudge-learnings
3. Follow that reference, then continue the user's task.

Examples

Example 1

Nudge blocks an edit that adds a forbidden pattern.

Expected behavior:

1. Read the Nudge message and snippet.
2. Change the edit to satisfy the rule.
3. Retry the operation.
4. Mention the rule only if it matters to the user-facing summary.

Example 2

User says: "Add a Nudge rule that blocks npm install."

Expected behavior:

1. Read references/rule-writing.md.
2. Add or update the appropriate .nudge.yaml or .nudge/*.yaml rule.
3. Read references/validation.md.
4. Run the checks that prove the new rule parses and behaves as intended.

Example 3

Nudge surfaces learned context from .nudge/learned.

Expected behavior:

1. Use nudge-learnings.
2. Inspect the cited note.
3. Apply it only if it matches the current situation.

Example 4

After debugging, the agent fixes a repo-specific issue that future agents are likely to hit again.

Expected behavior:

1. Use nudge-learnings.
2. Record a concise learned incident note under .nudge/learned with the symptom, root cause, fix, and verification.
3. Keep the note repo-specific; do not record generic programming advice.

Example 5

User asks: "Why did Nudge rewrite my command?"

Expected behavior:

1. Read the substitution context from the hook response.
2. If the reason is not obvious, read references/hook-responses.md.
3. Explain the original command, the rewritten command, and why the rule prefers the rewrite.

Example 6

User says: "This Nudge rule keeps blocking the wrong thing."

Expected behavior:

1. Read references/rule-debugging.md.
2. Reproduce the noisy match with nudge test, nudge check, or the smallest relevant hook payload.
3. Tighten the matcher or message, then rerun the proof command.

Example 7

User says: "Add Nudge to CI."

Expected behavior:

1. Read references/ci.md.
2. Add a scripted nudge check gate without depending on live agent hooks.
3. Run the CI command locally when practical.

Example 8

User says: "I cloned this repo and it has .nudge.yaml, but Nudge isn't doing anything."

Expected behavior:

1. Read references/setup.md.
2. Check whether nudge is installed and which agent hooks are needed.
3. Run the relevant setup command from the project root.
4. Verify hooks and skills after restarting the agent session.

Supporting Files

• references/ci.md: nudge check in CI, pre-commit, and scripted gates.
• references/hook-responses.md: provider surfaces and response types.
• references/setup.md: local binary install, hook setup, skill install, and verification.
• references/rule-writing.md: rule locations, schema, and examples.
• references/rule-debugging.md: diagnosing noisy, silent, or surprising rules.
• references/validation.md: choosing validate, test, and check.