wiki-sync

Wiki Sync

Wiki Zones

Per the wiki-zone model in CONCEPT.md, route wiki knowledge through namespace zones:

• wiki/<namespace>/ — product/domain knowledge for one namespace: its concept, vocabulary, architecture, and app/API behavior. One zone per product, customer, domain, or workstream namespace the team defines.
• wiki/platform/ — shared implementation substrate: infrastructure, deploys, dependencies, environments, and cross-namespace implementation details.
• wiki/general/ — team/brain workflow operating knowledge: lifecycle semantics, conventions, and process principles.

Boundary rule: route by implementation sharing, not by topic. If changing the knowledge would force edits in more than one namespace's code, use platform; if it only touches one namespace's code, use that namespace's zone even when the concept sounds shared.

Fixed-path exceptions: wiki/decisions/index.md, wiki/logs/, and wiki/index.md stay at the wiki root. ADR files live under wiki/decisions/<zone>/ while retaining global ADR numbers and Namespace: fields (a product namespace, platform, or general).

If the wiki predates zones, tolerate a half-migrated layout: read/update existing legacy root pages when a repos.yaml feed still points there, but classify the intended zone and call out any future move needed. Do not move wiki pages as part of this skill unless the user explicitly asks for a migration.

Two input modes — PR mode for post-merge sync, doc mode for ingesting existing implemented knowledge that has no PR or predates the workflow.

Mode detection

PR Mode

Use after a PR merges to the default branch in an implementation repo (any repo registered under repos[] in repos.yaml). Brain repo PRs can also be implementation PRs when they implement workflow, skill, wiki behavior, or repo metadata described by a plan.

Inputs

1. PR number on the default repo: /wiki-sync 1234 (defaults to the first role: implementation repo in repos.yaml)
2. Cross-repo PR: /wiki-sync owner/repo#1234
3. PR URL: /wiki-sync https://github.com/owner/repo/pull/1234
4. Merged commit SHA: /wiki-sync sha:abc123
5. No argument: list the most recently merged PRs not yet in wiki/logs/synced-prs.md, prompt the user to pick one

Step 1 — Read context

Read repos.yaml, CONCEPT.md, wiki/index.md, and wiki/decisions/index.md.

Step 2 — Resolve the PR

gh pr view <pr> --repo <owner/repo> --json title,body,files,mergedAt,labels,state,headRefName,closingIssuesReferences

Require state=MERGED. If the PR is not yet merged, stop and tell the user.

Canonicalize the PR identity before idempotency checks:

• Prefer the GitHub API owner/repo and PR number.
• Treat PR URLs and owner/repo#N references as the same PR when the repo name and PR number match.
• Check wiki/logs/synced-prs.md by canonical identity, not exact URL text only.

If the canonical PR identity already appears in wiki/logs/synced-prs.md, report "already synced", note any known archive state if relevant, and stop without moving files again.

Step 3 — Identify and verify the bound plan file and source idea

Look for a reference to a plan file in this order:

1. The PR body ## Lifecycle section, accepting Plan: plans/<namespace>/<feature-slug>/<phase-slug>.md or Plan: plans/<namespace>/<feature-slug>/.
2. A line matching plans/<namespace>/<feature-slug>/<phase-slug>.md elsewhere in the PR body.
3. Scan plans/ for a phase slug that matches the PR title or branch name.
4. Ask the user: "Which plan file or folder does this PR correspond to? (e.g. plans/general/auth-rewrite/phase-1-token-storage.md, plans/general/workflow-fix/, or 'none')"

If the user says "none" or no plan file is found, skip plan/source archive cleanup at the end.

When a plan file is found, resolve the source idea from:

1. The PR body ## Lifecycle section line Source idea: ....
2. The plan frontmatter field source_dump.
3. A source idea file whose related_plan points at the plan path or folder.

Do not invent a source idea if none is found.

Before proceeding with archive cleanup, verify the lifecycle chain:

• The PR body Plan: value must match the resolved plan path or folder.
• The PR body Source idea: value, when present, must match the plan source_dump.
• If the PR body has Implementation scope: none or only an artifact scope, do not archive plan/source files or mark lifecycle implementation complete. Continue wiki/ADR sync if appropriate.
• The source idea related_plan, when present, must match the resolved plan path or folder.
• The plan/source related_pr, when present, must match the canonical PR identity.
• The plan/source artifact_pr, when present, is provenance only and must not be used as implementation evidence.
• If any values conflict, stop archive cleanup and ask the user to confirm the correct chain. Continue wiki/ADR sync if possible, but do not archive conflicting lifecycle files.

Step 4 — Resolve or create the ADR

Look for an existing bound ADR in this order:

1. Any closing issue with an adr:NNN label → search wiki/decisions/*/adr-NNN-*.md and read the matching ADR
2. A line matching wiki/decisions/<zone>/adr-NNN- in the PR body
3. The head branch name matching ^adr-NNN-

If an existing ADR is found: proceed to Step 5 to flip its status.

If no ADR is found: create one now.

• Find the highest existing ADR number:

  python3 -c "from pathlib import Path; print(sorted(Path('wiki/decisions').glob('*/adr-*.md'))[-1])"
  

  Increment by 1. Use zero-padded 3-digit format: adr-001-, adr-002-, etc., and write the file under the classified decision zone.

• Derive the slug from the PR title or plan file name (kebab-case).

• Write wiki/decisions/<zone>/adr-NNN-<slug>.md:

  # ADR NNN: <Title>
  
  Status: accepted
  Date: YYYY-MM-DD
  Namespace: <product namespace | platform | general>
  Implemented-by: <PR URL>
  Implemented-on: YYYY-MM-DD
  
  ## Context
  
  <1-2 sentences on why this was built and what problem it solves — derive from PR body or plan file>
  
  ## Key Design Decisions
  
  Bullet list of the meaningful choices made in this phase. Derive from the "Key Design Decisions" section of the plan file. Each bullet should state the choice and the reason behind it.
  
  - **<Decision>** — <why this approach was chosen over alternatives>
  - …
  
  ## Alternatives Considered
  
  <For each rejected alternative: what it was and why it was ruled out. Derive from plan file if available, otherwise "Not recorded.">
  
  ## Consequences
  
  <Bullet list of outcomes and trade-offs — what this enables, what it costs, what to watch.>
  
  ## Sources
  
  - PR: <PR URL>
  - Plan: `<plan file path if available>`
  
  ## Related
  
  - [Decision index](../index.md)
  

• Update wiki/decisions/index.md — add the new ADR under its zone group.

Step 5 — Update ADR status (if ADR already existed)

In wiki/decisions/<zone>/adr-NNN-<slug>.md:

• Change Status: proposed → Status: accepted
• Add or preserve Namespace: using the wiki-zone boundary rule
• Add after the status line:
  • Implemented-by: <PR URL>
  • Implemented-on: YYYY-MM-DD

Step 6 — Identify affected wiki pages

gh pr view <pr> --repo <owner/repo> --json files --jq '.files[].path'

For each changed file, look up repos[name].sources[path].feeds in repos.yaml to find the downstream wiki pages, then run those targets through the zone-aware target resolution rules below.

Step 7 — Update affected wiki pages

For each wiki page from Step 6: read the current page, add or update a brief synthesis section. Do not paste the diff wholesale. Preserve source authority with a link or path. Mark uncertainty explicitly.

Step 7.5 — Write Tunable Knobs to engineering wiki

If the plan file has a "Tunable Knobs and Notes" section with any content, append it to wiki/platform/engineering/tunable-knobs.md (create the file if it doesn't exist):

## <ADR title> (ADR NNN)

> Source: `<plan file path>` — ingested YYYY-MM-DD

<Paste the Tunable Knobs section verbatim from the plan file>

This preserves operational knowledge (thresholds, caps, timeouts, signals to watch) that would otherwise become harder to find after the plan file is archived. If there are no tunable knobs, skip this step.

Step 8 — Append to wiki log

Append to wiki/logs/index.md:

### YYYY-MM-DD — <ADR title or PR title>

- PR: <PR URL>
- ADR: <ADR path> (status → accepted)
- Wiki pages updated: <list>
- Sources consulted: <list of changed source files>

If wiki/logs/index.md exceeds ~20 entries, move older entries to wiki/logs/YYYY-MM.md and keep the last 5 in index.md.

Step 9 — Record in synced-prs ledger

Append to wiki/logs/synced-prs.md (create if missing):

<PR URL> synced <YYYY-MM-DD>

Step 10 — Archive plan and source idea files

Archive cleanup is allowed only when the whole linked idea/plan chain is complete. A source idea linked to a plan folder remains active until every linked phase file is synced, archived, or explicitly included in the completed implementation scope. Do not archive a source idea merely because one phase in its plan folder merged or because a planning/artifact PR landed.

Treat these statuses as complete for archive-scope checks: implemented-and-synced and archived. Treat pr-open as complete only when related_pr matches the merged PR being synced and the phase is explicitly included in the PR implementation lifecycle scope. Never treat artifact_pr alone as complete. Treat wip, ready to ship, implemented-pending-pr, missing status, and unknown

Content truncated.