sync · diff
git:20260429.7c5e316 to git:20260708.cf1acae
4 added, 4 removed. Audit A to A.
---
name: sync
description: >
This skill should be used when the user asks to "document sync patterns",
- "map sync handlers", "create SYNCS.md", "audit sync coordination",
- "wyx sync", "wyx", or wants to understand how concepts communicate
+ "map sync handlers", "create SYNCS.md", "review sync coordination",
+ "wyx sync", or wants to understand how concepts communicate
through orchestrated workflows. Produces SYNCS.md coordination maps.
- argument-hint: "e.g. src/lib/server/syncs/ or Stock-to-Indicators pipeline"
+ argument-hint: "e.g. src/lib/server/syncs/, Order fulfillment → Inventory update, or leave empty to discover"
allowed-tools: Read, Glob, Grep, Write, Edit
---
# Sync Coordination Mapping
Generate a **sync coordination map** — a structured description of how
independent concepts interact through synchronization handlers. A sync map replaces
reading dozens of handler files with a single page showing the coordination topology,
timing patterns, and error strategies.
Syncs implement the execution mechanics of concept interactions. Where CONCEPT.md
`## interactions` declares relationships, SYNCS.md specifies the **execution mechanics**:
when the sync fires, what data flows, when it skips, and how errors propagate.
## How to interpret $ARGUMENTS
Determine the mode from the argument:
- **Path to sync directory** (e.g. `src/lib/server/syncs/`): **Retrofit mode** — read the existing sync handlers, map the coordination patterns, and propose a SYNCS.md. Flag any patterns that bypass concept boundaries.
- **Sync description** (e.g. `Order fulfillment → Inventory update`): **Greenfield mode** — design a sync spec for the described coordination. Define trigger, flow, qualification, and error strategy.
- - **No arguments**: **Discovery mode** — analyze the project for sync-like patterns (event handlers, cross-concept calls, scheduled jobs, dispatch registrations) and list candidates. Do NOT generate full specs; ask the user which to elaborate.
+ - **No arguments**: **Discovery mode** — analyze the project for sync-like patterns (event handlers, cross-concept calls, scheduled jobs, dispatch registrations) and list candidates. Do NOT generate full specs; ask the user which to elaborate. If discovery surfaces data transformation chains without cross-concept coordination, note that `/wyx:pipeline` covers those.
## SYNCS.md Format
Write the spec as a `SYNCS.md` file placed **in the sync directory** (e.g. `src/lib/server/syncs/SYNCS.md`).
```markdown
# syncs: [Module/Area Name]
## coordination graph
[Text diagram showing concept-to-concept flow through syncs]
[Concept] --(action)--> (SyncName) --> [Concept]
[Concept] --(action)--> (SyncName) --> [Concept]
--> [Concept]
## dispatching
- pattern: [event-driven | explicit-call | hybrid]
- error-isolation: [sync failure does NOT propagate to source | propagates]
- depth-limit: [max cascading depth, if applicable]
- context: [how correlation/tracing works across sync boundaries]
## sync: [SyncName]
trigger: [Concept.action | schedule(interval) | manual]
timing: [post-action | pre-validation | scheduled]
flow:
1. [Concept.action] → [what data is read]
2. [transform/filter/validate] → [what happens]
3. [Concept.action] → [what data is written]
qualification: [conditions for execution vs skip]
error: [isolated | propagates | skip-and-log]
file: [relative path to implementation]
```
## Design Rules for Sync Patterns
1. **Syncs live between concepts**: A sync never belongs to a single concept. It
coordinates two or more concepts. Place sync code in a dedicated directory, not
inside concept directories.
2. **One direction per sync**: Each sync has a clear source and target. If two
concepts need bidirectional coordination, use two separate syncs. This keeps
the coordination graph acyclic and prevents cascading loops.
3. **Three timing patterns**:
- **Post-action**: Runs AFTER source concept's action completes. Source succeeds
regardless of sync outcome. Error-isolated.
- **Pre-validation**: Runs BEFORE target concept's action. Validates cross-concept
references. Blocks the target action on failure. Error-propagating.
- **Scheduled**: Runs on a timer. Checks what needs updating, processes in batch.
Independent of individual concept actions.
4. **Qualification over silent filtering**: Sync handlers should declare explicit
qualification criteria (when to execute, when to skip). This makes the coordination
graph truthful — you can see exactly when a sync fires vs when it is skipped.
5. **Error isolation by timing**: Post-action syncs should NOT fail the source action —
the source concept completed its work. Pre-validation syncs SHOULD fail the target
action — that is their purpose. Scheduled syncs should log errors and continue
processing remaining items.
## Retrofit Mode Guidelines
When analyzing existing sync code:
1. Read all sync handler files in the directory
2. Read the index/registry file to understand registration and dispatch patterns
3. Read any dispatcher or context module to understand execution infrastructure
4. Map each sync to: trigger → flow → target
5. Classify timing patterns (post-action, pre-validation, scheduled)
6. Check for concept boundary violations within syncs (direct database imports
for data owned by other concepts)
7. Note error handling strategies and correlation tracking
Present findings as:
```
## patterns detected
- [N] post-action syncs (event-driven, error-isolated)
- [N] pre-validation syncs (called before target action, error-propagating)
- [N] scheduled syncs (periodic batch processing)
## boundary concerns
- [file:line] sync directly queries [table] owned by [Concept] — should use [Concept.action]
```
## Greenfield Mode Guidelines
When designing from a sync description:
1. Identify source and target concepts (must each have CONCEPT.md or be candidates)
2. Determine timing: post-action, pre-validation, or scheduled?
3. Define the data contract: what fields flow from source to target?
4. Specify qualification criteria: when does this sync execute vs skip?
5. Choose error strategy based on timing pattern (see Design Rule 5)
6. Consider cascading: can this sync trigger another sync? If so, declare depth limits
## After Generating
1. Present the sync map to the user for review
2. Ask: "Are the timing patterns correct? Should any syncs be split or merged?"
3. Only write the `SYNCS.md` file after the user approves
4. If a `SYNCS.md` already exists, show a diff of proposed changes
5. If `ARCHITECTURE.md` exists in the project, remind the user: "SYNCS.md changed — run `/wyx:map` to regenerate ARCHITECTURE.md." The `## coordination graph` is the highest-priority source for architecture map edges (per `/wyx:map` Step 2 priority order #1), so sync changes are graph-relevant.
6. If related CONCEPT.md specs exist, suggest: "Run `/wyx:concept drift` to verify
sync references match current concept declarations."
## Relationship to Other wyx Skills
- **`/wyx:concept`**: Each concept in the coordination graph should have a CONCEPT.md.
SYNCS.md references concept actions declared in CONCEPT.md specs.
CONCEPT.md `## interactions` is the concept's view of its sync relationships.
SYNCS.md is the sync directory's view of the same relationships — with execution details.
**Placement**: Keep all syncs in a single SYNCS.md per sync directory — the coordination graph requires a complete view of all sync flows. See `/wyx:concept` for hook traversal behavior.
- **`/wyx:pipeline`**: When a sync includes data transformation stages, those stages may also
appear in a PIPELINE.md. SYNCS.md handles coordination; PIPELINE.md handles data quality.
A sync that transforms data should reference its PIPELINE.md.