Hook Rule Interviewer

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