Sync Rules

---
name: sync-rules
description: >
  Iteration closeout knowledge routing for AI-assisted development. Use when the
  user asks to summarize changed function points into a knowledge base, update
  project docs or generated superpower docs after code changes, sync rules,
  distill lessons from an iteration, record durable decisions, or remember user
  preferences. Routes distilled knowledge to personal notes (K1), project docs
  (K2), agent memory suggestions (K3), or project instructions such as AGENTS.md
  and CLAUDE.md (K4), with preview and safety checks before writing.
---

# sync-rules

Use this skill to close an AI-assisted development iteration by extracting
durable knowledge from actual changes and routing it to the right target. Do
not treat every invocation as a full sync across all layers.

## Targets

| Target | Use For | Default Policy |
| --- | --- | --- |
| K1 personal knowledge base | Reusable lessons, decisions, research, plan evolution | Preview, then append history and update current view if present |
| K2 project docs | Feature summaries, usage docs, generated superpower docs, implementation docs | Scoped edits to relevant docs |
| K3 agent memory suggestion | Durable user preferences and cross-project working style | Suggest only unless user explicitly says to remember |
| K4 project instructions | Stable rules future agents must obey, such as `AGENTS.md` or `CLAUDE.md` | Confirm before editing |

## Core Rules

1. Route before writing. Decide K1/K2/K3/K4 from the user's intent and the
   evidence; do not update all targets by default.
2. Distill next-useful knowledge, not a work log. Avoid relative dates and
   process narration.
3. Preserve historical thinking in K1. Keep research, requirements analysis,
   original plans, and decision rationale as history; append dated adjustments.
   Keep a separate current note or current section up to date for latest
   architecture, behavior, usage, and run instructions.
4. Create missing K1 files when appropriate. If the knowledge-base path is
   configured but no matching note exists, propose a new file path, note type,
   and initial content; create it only after preview/confirmation or when the
   user explicitly asked to create/write the knowledge-base entry.
5. Use a K1 adapter based on `k1_type`. For `obsidian`, preserve or create YAML
   frontmatter and use an Obsidian-aware writer only when it is configured and
   available; otherwise use direct Markdown editing with frontmatter safeguards.
   For `plain-notes`, write Markdown directly. `k1_writer` may force `direct`,
   request `auto`, or name a configured tool, but it must never be guessed.
6. Treat K4 as rare. Only change project instructions when the result is a
   durable project rule, not just a feature update.
7. Preview writes. K3 and K4 always require explicit confirmation. K1 defaults
   to preview-then-append. K2 may be edited directly only when the requested doc
   target is unambiguous.
8. Match the user's language. Write generated prose in the same language as the
   user's request unless the user explicitly asks otherwise. Keep code names,
   paths, commands, filenames, API names, and quoted identifiers unchanged.
9. Follow local project instructions first. In this repository, development docs
   belong under `docs/<branch>/`; on branch `main`, use `docs/main/`.
10. Keep personal paths local. Use `.sync-rules/local.yml` for knowledge-base
   paths and never commit user-specific paths.
11. Do not support legacy schemas. This is a new skill: ignore neither silently
   nor compatibly read old field names such as `l4_path` or `l4_type`. Treat
   them as invalid configuration and require a K1-only config.

## Workflow

### 1. Detect

Collect focused evidence:

- Read the user's exact request and infer the requested target if clear.
- Run `git status --short`.
- Read focused diffs for changed source/docs with `git diff`.
- Read related existing docs before editing them.
- Read `.sync-rules/local.yml` only if K1 is needed and the file exists.

Do not perform broad repository scans unless the user asks for a full audit.

### 2. Classify

Classify each candidate item:

- `feature-change`: user-visible behavior or capability changed.
- `doc-drift`: docs no longer match implementation.
- `decision`: design or architecture choice worth preserving.
- `bugfix-learning`: reusable lesson from a fixed issue.
- `preference`: durable user preference or working style.
- `stable-rule`: future agents must follow this project rule.
- `noise`: formatting, generated churn, temporary experiment, or non-durable detail.

Drop `noise` unless the user explicitly asks to document it.

Read `references/routing.md` when the route is not obvious.

### 3. Distill

Turn each non-noise item into a concise rule, note, or doc update:

- Write what should be true next time.
- Use absolute dates when a date matters.
- Compare against existing target content to avoid duplicates.
- Mark conflicts or uncertain replacements for user confirmation.

Read `references/distillation.md` for examples and anti-patterns.

### 4. Route

Map each item to targets:

- `feature-change` -> K2; K1 only if it teaches a reusable pattern.
- `doc-drift` -> K2.
- `decision` -> K1; K2 if humans need the current result.
- `bugfix-learning` -> K1; K2 if it affects operation or usage.
- `preference` -> K3.
- `stable-rule` -> K4; K2 if humans also need it.

Read `references/targets.md` before editing K1, K3, or K4.
Read `references/k1-adapters.md` before creating or editing K1 notes.
Read `references/safety.md` before creating or using `.sync-rules/local.yml`.

### 5. Preview

Before edits, show:

- Distilled items.
- Classification.
- Target files or memory suggestions.
- Operation type: append, current-section update, scoped doc edit, or suggestion.

If the user requested a specific docs update and the target is unambiguous, K2
edits may proceed after a concise preview. K1, K3, and K4 require stricter
confirmation as described above.

### 6. Apply and Verify

Apply only confirmed or unambiguous edits. Then run the checklist in
`references/self-check.md`.

## Output

End with a concise summary:

```markdown
## sync-rules complete

Updated:
- K1: <path> - appended decision adjustment and refreshed current summary
- K2: <path> - updated feature behavior

Suggested memory:
- <only if K3 was requested but not written>

Not changed:
- K4 project instructions - no stable project rule detected

Needs confirmation:
- <open question, if any>
```

Only list targets that were actually updated or intentionally skipped for a
reason.