check

Original source / Raw SKILL.md

---
name: check
context: fork
description: |
  This skill should be used when the user wants to verify their changes
  before pushing, or update the project's rule checklists.
  Phase 1: validate changed files against .dev/rules/ checklists and report
  PASS/WARN. Phase 2 (conditional): propose rule additions when unmatched
  patterns are detected. Essential before git push.
  Trigger phrases: "check", "checklist", "verify changes", "what did I miss",
  "pre-push check", "cascading changes", "any more changes needed",
  "update checklist", "update rules", "rules update",
  "체크", "체크리스트", "변경 확인", "빠뜨린 거 없나", "push 전 확인",
  "뭐 더 건드려야 해?", "연쇄 변경 확인", "규칙 갱신".
---

# Check — Change Verification + Rule Evolution

> Analyze git diff against `.dev/rules/` to catch missed cascading changes, then propose rule updates when new unmatched patterns are detected.

**Prerequisite**: The project must have a `.dev/rules/` directory containing rule files with YAML frontmatter. If `.dev/rules/` does not exist, guide the user to create it: `mkdir -p .dev/rules`, then help them write their first rule file following `${baseDir}/references/rules-authoring.md`.

**Two-phase structure:**
- **Phase 1** (always): Validate changes — produce PASS/WARN results
- **Phase 2** (conditional): Propose rule updates — only when unmatched patterns exist

---

## Phase 1: Change Validation

### 1. Collect Changed Files

```bash
# Gather committed + uncommitted changes
git diff --name-only HEAD~1..HEAD
git diff --name-only --cached
git diff --name-only
```

Deduplicate and store as `CHANGED_FILES`.

### 2. Build Rule Graph and Match

Read YAML frontmatter from all `.dev/rules/*.md` files to construct the rule graph. Refer to `references/rules-authoring.md` ("Structure" section) for the frontmatter schema.

**Matching order:**
1. Glob-match each file in `CHANGED_FILES` against every rule's `triggers` patterns
2. Follow `depends_on` edges from matched rules to pull in related rules (1-depth only)
3. Finalize the active rule set
4. **Store unmatched files separately as `UNMATCHED_FILES`** (used in Phase 2)

**Note:** Meta documents (e.g., RULES.md) are excluded from matching.

### 3. Parallel Subagent Verification

Spawn one subagent per active rule using the **Agent tool (`subagent_type="general-purpose"`)** and run them in parallel.

Pass each subagent:
- The `CHANGED_FILES` list
- The rule file's body (checklist content)
- The actual diff of changed files (`git diff`)

Each subagent:
1. Applies checklist items against CHANGED_FILES
2. Identifies cases where a file was changed but related files were not
3. Reads the actual diff for WARN items to determine if the omission is genuine
4. Returns results classified as PASS / WARN / Not Applicable

### 4. Aggregate and Output Results

Collect all subagent results and output them **grouped by category**: domain rules first, then concern rules, then pipeline rules.

```
## Phase 1: Verification Results

### PASS (N items)
#### domain
- [billing] schema.ts changed -> migration file created
#### concern
- [infra] .env changed -> terraform synced
#### pipeline
- [api-codegen] swagger changed -> types regenerated

### WARN (N items)
#### concern
- [ux] en.json changed -> ko.json not updated

### Not Applicable (N items)
- [docs] no docs/ changes
```

### 5. Execute agents/commands

If active rules have `agents` or `commands` fields:

- **agents**: Run automatically via the Agent tool for additional verification. Merge any WARNs from agent results into the Phase 1 WARN list.
- **commands**: Present the commands to the user for manual execution (e.g., `pnpm generate:api`).

### 6. Process WARNs

For each WARN item:
1. Read the changed code to determine whether a change is actually needed
2. Distinguish between intentional omissions and accidental misses
3. For genuine misses, specify exactly which file and section needs modification

---

## Phase 2: Rule Update Proposals (Conditional)

> **Phase 2 trigger conditions** — Execute Phase 2 if ANY of the following is true:
> 1. `UNMATCHED_FILES` contains at least one meaningful source file (`.ts`, `.tsx`, `.json`, `.yaml`, `.tf`, etc.) — exclude meta files (`.md`, lock files, etc.)
> 2. Any WARN from Phase 1 indicates a **rule gap** (not a rule violation)
>
> **Skip condition**: If `UNMATCHED_FILES` is empty AND no WARNs indicate rule gaps, skip Phase 2 and proceed directly to follow-up actions (step 9).
>
> **Distinguishing rule gaps from rule violations**: If a WARN was caused by violating an existing checklist item, it is a rule violation (handled in Phase 1). If no checklist item exists anywhere that could have caught the WARN in advance, it is a rule gap — this triggers Phase 2.

### 7. Analyze Patterns and Cross-Reference Rules

Analyze `UNMATCHED_FILES` and Phase 1 WARN results to identify:

- **Uncovered change patterns** — file changes not matched by any rule's `triggers`
- **Near-miss cascading changes** — duplicate logic across multiple locations where only some were updated
- **Newly discovered sync points** — relationships where changing one location requires updating another

Read `references/rules-authoring.md` for authoring guidelines, then classify findings:
- **Existing rule needs new items** — propose the rule file and specific items to add
- **New rule file needed** — entirely new pattern not covered by any existing rule; include the `category` field (domain | concern | pipeline)

### 8. Output Rule Update Proposals

```
## Phase 2: Rule Update Proposals

1. [subscriptions.md] Add sync check for URL detection functions across 3 apps
   - Reason: isSubstackUrl() duplicated in 3 locations, only 2 updated
2. [New file: webhook.md] Add sync check for webhook event changes
   - category: domain
   - Reason: new domain with no existing rule coverage
```

**Confirm each proposal with AskUserQuestion:**
- **"Add"** — Apply the item to the rule file
- **"Edit & Add"** — Adjust the content before adding
- **"Skip"** — Unnecessary, skip this item

Apply approved items to the corresponding rule files. For new rule files, create them with frontmatter (`category` and `triggers` are required).

After adding or modifying rules, verify that the frontmatter `triggers` patterns correctly match the intended files.

---

### 9. Follow-Up Actions

Consolidate WARNs from Phase 1 and rule updates from Phase 2 into a follow-up change list.

If one or more WARN items exist, present the list and use **AskUserQuestion** to ask the user:

- **"Fix All"** — Automatically fix all WARN items
- **"Select"** — Choose specific items to fix (multiSelect)
- **"Ignore & Proceed"** — Treat as intentional omissions, finish without changes

When "Fix All" or "Select" is chosen, apply the fixes in order and display the updated results.

---

## Additional Resources

### Reference Files

- **`${baseDir}/references/rules-authoring.md`** — Rule authoring principles, frontmatter schema, category classification, and abstraction-level guidelines. Consult when creating or updating rules.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/rules-authoring.md

```markdown
# Rule Authoring Principles

## Purpose

Rules are **tools for catching cascading impacts of changes**. They encode the knowledge of "if you change this, you must also check that" — without requiring anyone to read through the code every time.

## Structure

Each rule file lives in the `.dev/rules/` directory. It declares graph edges via YAML frontmatter and contains checklist content in the markdown body.

```yaml
---
category:      # Classification (domain | concern | pipeline)
  domain
triggers:      # File glob patterns that activate this rule (required)
  - "apps/client/src/**/*.tsx"
depends_on:    # Other rules to check alongside this one (optional)
  - term
agents:        # Automated verification agents (optional)
  - analytics-auditor
commands:      # Commands to run (optional)
  - "pnpm generate:api"
---

# Checklist content (markdown)
```

### Execution Flow

```
git diff -> collect changed files
  -> glob-match against rules/*.md frontmatter triggers
  -> select active rules
  -> follow depends_on to add related rules
  -> verify per-rule checklists
  -> run agents field agents
  -> surface commands field commands
```

## Right Level of Abstraction

Checklist items should be at the **"what to verify"** level.

| Level | Example | Verdict |
|-------|---------|---------|
| Too abstract | "Check if UI is correct" | X — verify what exactly? |
| Just right | "CTA button text matches policy for each plan state (Free/Trial/Pro)" | O |
| Too specific | "Check `ctaButton` var at `PlanSection.tsx:138` for `isTrial && isOverLimit` branch" | X — breaks when code changes |

**Principle: Verify policies and rules, not specific lines of code.**

## Qualities of a Good Checklist Item

1. **Sync targets are explicit** — "Values in 5 scattered locations must match" with each location named
2. **Brief rationale** — A one-line reason such as "if any is missed, works locally but breaks in production"
3. **Verifiable** — Clear what to do to check the box. "Ensure good code quality" is not verifiable

## Frontmatter Guide

### category — Rule Classification

The `category` field declares what kind of concern a rule addresses.

| Value | Definition | Examples |
|-------|-----------|----------|
| `domain` | Invariants valid only within a specific business domain. Cross-cutting concerns should be delegated via `depends_on` | billing, digest, scheduling |
| `concern` | Cross-cutting patterns applied regardless of domain (performance, infra, UX, etc.) | performance, infra, ux, term |
| `pipeline` | File change -> command execution automation. Declares only `commands`, no checklist body | api-codegen |

**depends_on direction rules:**

- `domain -> concern` **allowed** — domain rules may reference cross-cutting concerns
- `domain -> pipeline` **allowed** — domain changes may trigger pipeline commands
- `concern -> domain` **forbidden** — cross-cutting patterns must not couple to specific domains, or reusability breaks

**Keep domain rules LEAN:**

Do not duplicate cross-cutting concern content in domain rule bodies. Use `depends_on` to reference the relevant concern rule instead. Duplication creates coupling — when the concern rule updates, the domain rule must also be modified.

```yaml
# Bad: billing.md directly includes infra checklist items
---
category: domain
triggers:
  - "**/billing/**"
---
- [ ] Added env block to terraform config  # <- belongs in infra.md

# Good: delegate via depends_on
---
category: domain
triggers:
  - "**/billing/**"
depends_on:
  - infra
---
- [ ] If new env vars added, check infra rule
```

### triggers — When This Rule Activates

**Principle: Start narrow, widen only when misses are discovered.**

| Pattern | Scope | Good for |
|---------|-------|----------|
| `"apps/server/src/**/*.dto.ts"` | Specific app, specific file type | Clearly scoped domains |
| `"**/billing/**"` | All apps, billing directory | Cross-app domains |
| `"apps/client/src/**/*.tsx"` | One app, broad scope | App-wide concerns (UI) |

- Patterns starting with `**` match across all apps — verify this is intentional
- Too broad: unnecessary rules activate on every change (noise)
- Too narrow: new files slip through without rule coverage

### depends_on — Rules to Check Alongside

**Principle: "When checking A, would skipping B cause a miss?" — if yes, add the dependency.**

- Circular dependencies are forbidden (A->B->A)
- Only 1-depth resolution — if A->B->C, activating A adds B but not C

### agents — Automated Verification for Repetitive Patterns

**"If someone is running the same grep check every time, turn it into an agent."**

- Agents are defined by name in the project's `.claude/agents/` directory
- Report-only agents (no code modifications) are the best fit

### commands — Commands to Execute

**"When a file change always requires running a specific command."**

- Best suited for deterministic commands: code generation, migration creation, type regeneration

## Adding / Modifying Rules

- **Filename**: lowercase kebab-case, singular domain name (`billing.md`, `api-codegen.md`)
- **`triggers` is required** — rules without triggers are never matched
- Organize sections by concern (policy, UI, tests, infra, etc.)
- If 3 or fewer items, a flat list without sections is acceptable
- Link related policy documents at the top of the file

## Maintenance

- Update rules when policies or architecture change
- If a checklist item breaks due to code refactoring (file renames, function renames), the item was too specific

```