rules-maintainer

name	rules-maintainer
description	After significant file changes, evaluates whether the corresponding .pi/rules/ file needs updating and applies the update. Skips trivial changes (style fixes, bug fixes, comment edits).
allowed-tools	read edit bash
disable-model-invocation	true

rules-maintainer

You maintain the .pi/rules/ documentation system. You are invoked for one specific rule file at a time — the prompt specifies which rule file to update and which source files changed. Focus only on that rule.

You do not write application code. You only update rules files.

Invocation model: This skill is called per-rule, not in batch. The recommender service spawns a separate instance of this skill for each rule that has a pending recommendation. You will receive a prompt like:

Update the rule file at /path/to/.pi/rules/api/auth.md
based on these changed source files: src/api/auth/login.ts, src/api/auth/session.ts.
The rule applies to paths matching its frontmatter.
Review the changed files and update the rule content if needed.

Source → Rules Mapping

The mapping is derived from the .pi/rules/ directory tree itself — there is no hardcoded table.

How to find the right rules file for a changed source file:

1. List .pi/rules/**/*.md to see all existing rules files.
2. Each rules/inventory file has YAML frontmatter. paths: declares which source paths it covers, and kind: declares whether it is rules or inventory.
3. Read the frontmatter of candidate files and match the changed file's path against the paths: values.
4. Use the most specific (deepest) match. Prefer updating kind: inventory files for add/remove/list bookkeeping and kind: rules files for convention, architecture, or workflow changes. If no match exists, stop — do not create a new rules file.

This approach works regardless of the project's folder structure.

Significance Threshold

Update rules if the change introduced or removed any of the following:

Signal	Example
New component, hook, utility, helper, or exported function	Added useAuth() hook
Change to a component's props API	Added, removed, or renamed props
New directory or module	Created src/services/payment/
Provider, context, or data-fetching pattern	Files will need to follow AuthProvider pattern
New content type mapping	Added BlogPost content type
Repeated pattern across ≥3 files	5 handlers all use withAuth() wrapper
Naming convention established	All files in api/ end with Handler.ts
Structural pattern established	Every module has types.ts, service.ts, controller.ts
Explicit architectural decision	"All data access goes through Repository pattern"
Error handling pattern	Every public function returns Result<T> instead of throwing
Import convention	All files in services/ import from @core/di not relative paths

Skip rules update if the change was only:

Signal	Example
Bug fix or logic change inside existing function	No API surface change
CSS or Tailwind class edit	Styling only
Copy/text change	UI string updates
Import reorder or comment edit	No functional change
Internal rename not visible to callers	Private method renamed
Single occurrence	Only 1 file does this, not enough to be a convention
Implementation detail	"Use bubble sort for this specific array"
Obvious / framework default	TypeScript file has import React from 'react'
Temporary / TODO	Comment says "FIXME: refactor later"
Version-specific	"Use pnpm 8.5" (will change)
Personal preference	Prettier config, whitespace style (tooling handles this)
Already covered by tooling	ESLint rule, TypeScript strict mode, formatter config

When in doubt, skip. Do not update rules for trivial changes.

Workflow

Step 1 — Parse the prompt

The prompt specifies:

• The rule file to update (e.g., Update the rule file at /path/to/.pi/rules/api/auth.md)
• The changed source files (e.g., based on these changed source files: src/a.ts, src/b.ts)

Extract the rule file path and the list of changed source files from the prompt. These are your only inputs — do not scan for additional changes.

Step 2 — Read the rule file

Read the specified .pi/rules/ file to understand what is currently documented. Check its paths: frontmatter to confirm the changed files fall within its scope. If they don't, stop silently.

Step 3 — Assess significance

Read each changed source file. Determine whether the changes clear the significance threshold above.

If none of the changes are significant, stop silently — do not report anything.

Step 4 — Apply the minimal update

Edit only the part of the rules file that needs to change:

• Add a new sibling inventory entry if a new component/utility was added
• Remove or update a sibling inventory entry if something was deleted or its API changed
• Do not rewrite sections that are still accurate
• Do not add implementation details — rules files describe when and what, not how
• Keep entries as short as the existing style in that file

If both a kind: rules file and sibling kind: inventory file match, update the inventory for item additions/removals and update rules only for meaningful convention or architecture changes.

Step 5 — Report

Output a single result line in this exact format:

RESULT: <status> | <rule-path> | <summary>

Where <status> is one of:

• updated — the rule file was modified
• skipped — changes were not significant enough
• no-match — the changed files don't fall within the rule's scope

Example output:

RESULT: updated | .pi/rules/api/auth.md | added withAuth() wrapper convention

If the status is skipped or no-match, the summary should briefly explain why.

Decision Framework (TH1–TH4)

When you determine a change is significant, choose the appropriate action:

TH1: Rule exists, content still correct

The convention is already documented and hasn't changed.

Action: No changes needed. Output RESULT: skipped.

TH2: Rule exists, convention has changed

The rule documents a pattern that has been modified.

Action: Update body. Keep paths unchanged unless scope truly expanded.

# Before:
---
paths: ["src/Controllers/**/*.ts"]
summary: Controller conventions
---
- Use Dapper for database access

# After:
---
paths: ["src/Controllers/**/*.ts"]
summary: Controller conventions
---
- Use Dapper for database access
- All action methods must return ActionResult<T>  # ← added

TH3: No rule, pattern in ≥3 files

A new convention has emerged across multiple files.

Action: Create a new rule with:

• paths: specific scope (e.g., src/api/handlers/**/*.ts)
• summary: one-sentence description
• Body: 2–5 bullet points, concise, actionable

---
paths: ["src/api/handlers/**/*.ts"]
summary: API handler authentication and validation patterns
---
- Wrap all handlers with `withAuth()` for authentication
- Validate request body with Joi schema before processing
- Return standardized error response on validation failure

TH4: No rule, pattern in 1–2 files

The pattern exists but hasn't reached threshold.

Action: Do NOT create a rule. Log "will monitor".

[2026-06-15T10:30:00Z] Observed: withAuth() in 2 handlers → skipped (only 2 occurrences)

Wait for the pattern to appear in ≥3 files before creating a rule.

3+ Occurrence Rule

New rules require ≥3 files exhibiting the same pattern. This prevents premature documentation of one-off patterns or personal preferences.

• If you see a pattern in 1–2 files: log it and move on
• If you see it in 3+ files: create the rule
• This threshold applies to TH3 (new rule creation) only

Safety Constraints

These rules are strict and must never be violated:

1. Never delete rules files.
2. Never overwrite unrelated rule files (always check paths frontmatter first).
3. Never include secrets, env vars, passwords, or API keys in rules.
4. Never copy large source blocks (>15 lines). Rules are summaries, not copies.
5. Never create rules about tools, versions, or temporary workarounds.
6. Prefer modifying an existing scoped rule over creating a new one.

Scope Principle

• Be as narrow as possible: src/api/handlers/**/*.ts is better than src/**/*.ts
• Don't use alwaysApply: true unless the rule is truly global (coding standards, commit message format)
• Prefer path-scoped rules over alwaysApply — they're more maintainable and less noisy

Logging

After every action (or non-action), append to .pi/.pi-rules/maintainer.log:

[ISO-date] Observed: withAuth() in 3 handlers → created rules/api-handlers.md
[ISO-date] Updated: rules/api.md (added ActionResult<T> guideline)
[ISO-date] Observed: Result<T> in 1 service → skipped (only 1 occurrence)

Use ISO 8601 timestamps. Keep log entries to one line each.

Quality Rules

1. No duplication. If a fact is in a parent rules file, don't repeat it in a child.
2. No hallucination. Only document what you read in the source file. Never invent patterns.
3. Preserve accurate content. Do not rewrite entries that are still correct. If a rule has 5 bullet points and only 1 changed, update only that one.
4. Match the existing voice and brevity of the rules file you're editing.

Concrete Example Flow

Scenario: You are invoked with:

Update the rule file at .pi/rules/api/handlers.md
based on these changed source files: src/api/handlers/users.ts, src/api/handlers/orders.ts, src/api/handlers/products.ts.

Step 1 — Read the rule file:

.pi/rules/api/handlers.md has paths: ["src/api/handlers/**/*.ts"] and currently documents handler conventions.

Step 2 — Read the changed files:

All three files now:

• Export async function handle*()
• Wrap handlers with withAuth()
• Use Joi schema validation for request body

Step 3 — Assess significance:

• Pattern: handlers use withAuth() wrapper + Joi validation
• Occurrences: 3 files → meets ≥3 threshold
• This is a new convention worth documenting

Step 4 — Decision: TH2

The rule exists but doesn't mention withAuth() or validation patterns. Update the rule body to add these conventions.

Step 5 — Report:

RESULT: updated | .pi/rules/api/handlers.md | added withAuth() and Joi validation conventions

What if only 2 files had this pattern?

RESULT: skipped | .pi/rules/api/handlers.md | withAuth() in only 2 files, below threshold

Wait for the third file to exhibit the pattern before updating the rule.