trotsky1997/hook-rule-interviewer

Hook Rule Interviewer

Help the user turn vague guardrail ideas into a concrete project-level hook policy.

This skill is interview-first. Do not jump straight into writing rule files unless the user explicitly asks for implementation. Your main job is to:

• inspect the repo enough to understand risks and workflows
• run a short focused interview
• produce a clear hook policy and rule matrix
• only then draft concrete Hookify or Pi hook rules if asked

Goal

By the end of the interview, produce a project-level hook plan that answers:

• which event surfaces matter for this repo
• what each hook should do
• where the user wants warnings vs blocking vs transforms vs approvals
• what rollout strategy and exceptions the team wants

Read First

Before asking questions, quickly inspect the repository for signals that reduce guesswork:

1. Existing hook or policy files:
   • .pi/hookify*.yaml
   • .pi/settings.json
   • .claude/, .agents/, .github/, .husky/, or similar automation folders
2. Project shape and tooling:
   • package.json, pyproject.toml, Cargo.toml, go.mod, Dockerfile
   • README.md, docs/, workflow files, test scripts
3. Risk-heavy areas:
   • deploy or release scripts
   • secrets or env handling
   • destructive shell usage
   • generated files, lockfiles, or migrations
4. Read references/event-playbook.md from this skill when you need a quick mapping from repo concern to Pi hook surface.
5. Read references/output-template.md before presenting the final interview result so your structure stays consistent.

Repo-Specific Fit

When this skill is used inside pi-hookify, bias your recommendations toward the current Hookify V2 design:

• YAML rule files under .pi/
• the on / when / do / respond DSL
• Pi-native event names such as input, tool_call, tool_result, before_agent_start, context, and user_bash
• no backward-compatibility assumptions for the old markdown/frontmatter format

If the user wants implementation after the interview, draft rules that match the current V2 schema rather than proposing legacy Hookify formats.

Interview Strategy

Keep the interview tight. Ask only what the repo cannot answer.

Prefer AskUserQuestion when you need structured tradeoffs, especially for:

• rollout mode
• warning vs block behavior
• approval policy
• scope or priority tradeoffs
• per-tool or per-team preferences

Always cover

1. Primary goal
   • What is the user optimizing for: safety, compliance, review quality, workflow consistency, release control, or productivity?
2. Hook surfaces
   • Which surfaces matter: input, tool_call, tool_result, before_agent_start, context, user_bash, session_before_*, before_provider_request, or observe-only audit hooks?
3. Enforcement mode
   • For each important surface, should the system notify, ask, request approval, transform, patch, block, or only observe?
4. Rollout mode
   • Should the team start with audit or warn-only, or go straight to blocking for high-risk cases?
5. Exceptions
   • Which files, commands, users, tools, branches, or workflows need exceptions?

Ask when relevant

• If the repo has release or deploy workflows: ask about release gating and approval boundaries.
• If secrets or credentials are present: ask whether detection is advisory or blocking.
• If the repo has multiple languages or toolchains: ask whether rules should be global or scoped by tool or file type.
• If the repo already has existing automation: ask whether Hookify should complement it or replace parts of it.
• If the team seems unsure about strictness: propose a staged rollout and ask them to choose it.

Recommended Question Order

1. What failures or mistakes are they trying to prevent?
2. What behaviors should always be intercepted?
3. Which ones should be warn-only at first?
4. Which tools or files are most sensitive?
5. What exceptions are legitimate and frequent?
6. How should the team validate the policy before broad rollout?

Output Contract

Always present your interview result using this structure:

1. Project Hook Policy Brief
2. Hook Coverage Matrix
3. Candidate Rule Set
4. Rollout Plan
5. Open Questions / Risks

Use the template in references/output-template.md.

Hook Coverage Matrix Rules

For each high-signal hook, specify:

• event name
• target scope or trigger
• intended behavior
• severity or rollout mode
• rationale
• exceptions or notes

Be concrete. The matrix should be close enough that another agent can implement it without redoing the interview.

Candidate Rule Set Guidance

When proposing rules:

• prefer a small number of high-signal rules over a noisy long list
• separate audit rules from blocking rules
• keep names stable and descriptive
• group by event family and business purpose
• call out which rules belong in project scope vs user-local scope

If the user asks for actual Hookify V2 rules, map the matrix into YAML rule files under .pi/, using the current on / when / do / respond rule shape.

Decision Heuristics

Use these defaults unless the user gives a better repo-specific answer:

• start with audit or warn-only for medium-risk workflow issues
• block or require approval for destructive shell, secret leakage, irreversible release actions, or branch-critical operations
• use before_agent_start and context sparingly; reserve them for policy framing and context cleanup
• use tool_call for the majority of concrete enforcement
• use tool_result when the team wants annotation, sanitization, or structured post-processing
• use user_bash only when the team cares about direct ! shell behavior from the operator
• keep observe-only hooks for audit trails, metrics, and gradual rollout learning

If the User Wants Implementation

After the interview is accepted:

1. restate the approved rule matrix compactly
2. identify which files or directories the new rules should live in
3. draft the actual YAML rules in .pi/
4. suggest a validation path such as a smoke test, a dry run, or a staged rollout

Do not silently implement while requirements are still fuzzy.

Success Signals

You are done when:

• the user can see which hooks matter and why
• each important hook has an intended behavior and rollout mode
• exceptions are captured explicitly
• the output is implementation-ready or very close
• another agent could take the interview result and build the rules without repeating discovery