Skip to content

Contributing to Sync

Working notes on how work happens in this repo. Process rules that have been learned the hard way and shouldn't be re-debated mid-task.

Scenario corpus work

No-bulk-audit policy

Scenario corpus rewrites and audits are processed one scenario at a time. No bulk passes.

When an audit identifies multiple scenarios needing the same kind of change (voice tightening, role rebalancing, scan-strip addition, etc.), each scenario is reviewed and rewritten individually — even when the change appears templatable. LLM-assisted rewrites happen one scenario at a time with human review per output, not batched into a single multi-scenario prompt.

Why this rule exists (two prior incidents, both costing rework):

  1. The Apr 23 static-arc rewrite (memorialized in memory/project_static_arc_audit_pattern.md): First-pass batch rewrite of 152 arc-bound scenarios produced output that introduced inventions even under tight prompts. Required a second full pass with manual review per scenario. The first pass was effectively discarded.

  2. The May 22 v1.7.0 arc-bound rewrite (CHANGELOG, "Arc rewrite complete"): A streaming agent processed 148 scenarios before timing out; the remaining 4 had to be completed inline. The successful pattern was per-scenario, not batched.

The rule isn't about LLM capability ceiling — it's about the audit signal that emerges when a human reviews each output. Bulk passes hide outliers in the bulk. One-at-a-time forces the reviewer to confront each rewrite individually, which is exactly where the gotchas live (invented characters, wrong tone, lost specificity, regressed quality).

User framing from May 1: "do not batch bulk anything, and do the rewrites here as needed."

Scope: Applies to corpus rewrites and audits. Does NOT apply to corpus generation — the live scenario generator produces scenarios one at a time by design, and pre-generated themed batches have their own quality gates (ADR-061 pre-commitment planning, scan-strip + cast-block validation).

Tooling implication: Any "batch rewrite" CLI or script should be considered a smell. Wrap per-scenario human approval in any such tool. If you find yourself writing a for scenario in scenarios: rewrite(scenario) loop without a pause for review per iteration, stop.

Trigger to relax: If a future LLM generation produces zero invention errors across a controlled 50-scenario batch with human-graded review, the rule may be safe to relax. Don't relax until that evidence exists.

See also: ADR-029 (static-arc audit pattern), memory project_static_arc_audit_pattern.md (the Apr 23 cautionary tale).

Self-contained prompts

When writing prompts for corpus work, prefer self-contained prompts that could be pasted into an incognito window with no project context. This makes them portable across executors (Claude Code, Claude.ai web, scripts) and makes batch-writing-of-prompts safe even though batch-execution-of-rewrites is not.

Source: May 23 conversation, audit item 62.

ADR conventions

Architecture Decision Records (ADRs) capture significant technical decisions: new dependencies, pattern changes, API design, infrastructure choices, deferred features. They live in docs/decisions/. See docs/decisions/README.md for the index and docs/decisions/template.md for the format.

What's not an ADR: - Marketing/content commitments → goes in docs/briefs/ - Process rules that affect contributors more than architecture → goes in this file (docs/contributing.md) - Operational reminders or facts that need to be remembered across sessions → goes in memory/ (auto-memory) - Bug fixes and feature ships → goes in CHANGELOG.md

ADRs are never deleted or renumbered after publication. If an ADR is wrong-shaped or its content moves elsewhere, mark it Superseded and link to the new home. ADR numbers are referenced from commits, code comments, and conversations — renumbering breaks those references silently.

Write ADR-NNN in prose anywhere in docs/ (e.g. ADR-024) and the MkDocs build will rewrite it to a link to that ADR's page automatically. Do not add manual markdown links for ADR references in prose — source files stay clean and the link target is computed at build time.

The hook (mkdocs_hooks/linkify_adr_refs.py) is conservative: it skips references that are already inside a markdown link, inside backtick inline code, or inside a fenced code block, and never links an ADR page to itself. If you need to render the literal text ADR-NNN with no link (rare), wrap it in backticks.

This convention applies to all prose in docs/ — ADRs, briefs, research, contributing, etc.

Git workflow

  • After committing, always push to the remote branch (per CLAUDE.md)
  • Concise commit messages explaining the "why" not the "what"
  • Pre-commit hooks: investigate failures, don't --no-verify

Changelog discipline

Every meaningful code change gets a CHANGELOG.md entry in the current week's section. Match the existing format (weekly headers, category sections, bold titles with detailed explanations + sub-bullets). Don't duplicate entries.

Memory hygiene

Auto-memory at ~/.claude/projects/<project>/memory/ persists across Claude Code sessions. Save to memory:

  • User preferences, role, recurring feedback
  • Project context not derivable from code (deferred decisions with trigger conditions, external system pointers)
  • Stable conventions and process rules that aren't in CLAUDE.md

Don't save to memory: - Anything already in CLAUDE.md, ADRs, or CHANGELOG (avoid duplication) - Ephemeral task state (use TodoWrite for in-conversation tracking) - Code patterns or file paths derivable from reading the repo

When a memory turns out to be wrong or outdated, update or delete — don't accumulate stale entries.