Sync rules

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:

## 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.