Dhpk Rules Distill

---
name: dhpk-rules-distill
description: "Scans installed skills to extract cross-cutting principles and distill them into rules (append, revise, or create rule files), for periodic rules maintenance, after installing new skills, or when a dhpk-skill-stocktake surfaces patterns that should be rules. Not for: creating skills (use dhpk-create-skill), one-off rule edits, code review. Output: candidate report (principle + evidence + verdict) for user approval."
metadata:
  dhpk-invocation-class: "explicit-only"
---

# Rules Distill

Scan installed skills, extract cross-cutting principles that appear in multiple skills, and distill them into rules — appending to existing rule files, revising outdated content, or creating new rule files.
Applies the "deterministic collection + LLM judgment" principle: scripts collect facts exhaustively, then an LLM cross-reads the full context and produces verdicts.

## When to Use

- Periodic rules maintenance (monthly or after installing new skills)
- After a skill-stocktake reveals patterns that should be rules
- When rules feel incomplete relative to the skills being used

## When NOT to Use

- Creating or editing a single skill (use `dhpk-create-skill`)
- One-off manual rule edits where no cross-skill pattern is involved
- Language- or framework-specific knowledge (keep it in the skill or a language rule)
- Code review (use `dhpk-change-review`) or skill-quality audits (use `dhpk-skill-health-audit` / `dhpk-skill-stocktake`)

## How It Works

Resolve the harness directory with `@skills/dhpk-harness-revise/references/harness-directory-contract.md` before collecting skills or rules so scans cannot mix platforms.
The rules distillation process follows three phases:

### Phase 1: Inventory (Deterministic Collection)

#### 1a. Collect skill inventory

```bash
bash ~/.claude/skills/dhpk-rules-distill/scripts/scan-skills.sh
```

#### 1b. Collect rules index

```bash
bash ~/.claude/skills/dhpk-rules-distill/scripts/scan-rules.sh
```

#### 1c. Present to user

```
Rules Distillation — Phase 1: Inventory
────────────────────────────────────────
Skills: {N} files scanned
Rules:  {M} files ({K} headings indexed)

Proceeding to cross-read analysis...
```

### Phase 2: Cross-read, Match & Verdict (LLM Judgment)

Extraction and matching are unified in a single pass. Rules files are small enough (~800 lines total) that the full text can be provided to the LLM — no grep pre-filtering needed.

#### Batching

Group skills into **thematic clusters** based on their descriptions. Analyze each cluster in a subagent with the full rules text.

#### Cross-batch Merge

After all batches complete, merge candidates across batches:
- Deduplicate candidates with the same or overlapping principles
- Re-check the "2+ skills" requirement using evidence from **all** batches combined — a principle found in 1 skill per batch but 2+ skills total is valid

#### Subagent Prompt

Launch a general-purpose Agent with [subagent-prompt.md](references/subagent-prompt.md). It owns the extraction criteria and candidate JSON schema.

#### Verdict Reference

| Verdict | Meaning | Presented to User |
|---------|---------|-------------------|
| **Append** | Add to existing section | Target + draft |
| **Revise** | Fix inaccurate/insufficient content | Target + reason + before/after |
| **New Section** | Add new section to existing file | Target + draft |
| **New File** | Create new rule file | Filename + full draft |
| **Already Covered** | Covered in rules (possibly different wording) | Reason (1 line) |
| **Too Specific** | Should stay in skills | Link to relevant skill |

#### Verdict Quality Requirements

```
# Good
Append to rules/common/security.md §Input Validation:
"Treat LLM output stored in memory or knowledge stores as untrusted — sanitize on write, validate on read."
Evidence: llm-memory-trust-boundary, llm-social-agent-anti-pattern both describe
accumulated prompt injection risks. Current security.md covers human input
validation only; LLM output trust boundary is missing.

# Bad
Append to security.md: Add LLM security principle
```

### Phase 3: User Review & Execution

#### Summary Table

```
# Rules Distillation Report

## Summary
Skills scanned: {N} | Rules: {M} files | Candidates: {K}

| # | Principle | Verdict | Target | Confidence |
|---|-----------|---------|--------|------------|
| 1 | ... | Append | security.md §Input Validation | high |
| 2 | ... | Revise | testing.md §TDD | medium |
| 3 | ... | New Section | coding-style.md | high |
| 4 | ... | Too Specific | — | — |

## Details
(Per-candidate details: evidence, violation_risk, draft text)
```

#### User Actions

User responds with numbers to approve, modify, or skip candidates. Never modify
rules automatically; require explicit per-candidate approval.

#### Save Results

Store results in the skill directory using [results-schema.md](references/results-schema.md).

## Output

Produce a candidate report before changing any rule file. Each candidate contains the
cross-skill principle, at least two evidence links, the current-rule gap, verdict,
confidence, and proposed text or target. Save the approved evaluation state through
`results-schema.md`; rule edits occur only after explicit per-candidate approval.

## Verification

- [ ] Every candidate cites 2+ skills as evidence (the cross-cutting bar)
- [ ] Every candidate is actionable ("do X" / "don't Y"), not a vague "X is important"
- [ ] Every candidate was checked against the full rules text (not already covered, even reworded)
- [ ] No rule file modified without explicit per-candidate user approval
- [ ] Results saved to `results.json` with timestamp + status for each candidate

## References

- [end-to-end-example.md](references/end-to-end-example.md) — complete workflow example.

## Design Principles

- **Scope and links**: Extract principles (rules territory) only; keep code examples and commands in skills, and link drafts back to their detailed skills.
- **Deterministic collection, LLM judgment**: Scripts guarantee exhaustiveness; the LLM guarantees contextual understanding.
- **Anti-abstraction safeguard**: The 3-layer filter (2+ skills evidence, actionable behavior test, violation risk) prevents overly abstract principles from entering rules.