# Lw Sync Repo

> Inspect repo changes, classify them using the active profile, stage them into raw/, update manifest state, and recommend or trigger compile/lint/reflect actions. Usage: /lw-sync-repo <repo-path|commit-range|changed-files>

- Skill: `geeksfino/lw-sync-repo` (Agent Skill)
- Install (CLI): `npx skillmds@latest add geeksfino/lw-sync-repo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/geeksfino/lw-sync-repo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: geeksfino (https://skillmd.com/u/geeksfino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/geeksfino/lw-sync-repo

---


# LLM Wiki Sync From Repo

Keep a wiki live from source-repo changes.

## Required reads
1. `.llm-wiki/profile.json`
2. Active profile markdown
3. `.llm-wiki/manifest.json`
4. Repo change input provided by the user, if any

If the active profile is not repo-backed, stop and say that repo sync is not defined for the current profile.

## Source-of-truth location

The canonical repo location comes from the active profile's machine-usable block:

```yaml
repo_sync:
  enabled: true
  repo_path: raw/upstream
  repo_remote: origin
  default_branch: main
  provider: github
  repo_slug: owner/repo
```

This means:
- the source repo location is project-specific
- it should live in the workspace-local profile, not in the shared skill
- relative `repo_path` values should be resolved relative to the wiki workspace root
- **recommended** workspace-local mirror: `raw/upstream/` (created by `lw-clone-repo` or bootstrap `--repo-url`). Older workspaces may still use a sibling path such as `../source-repo`.
- **`raw/repo/`** is not the live checkout; it holds **staged** repo file artifacts for compile (see `lw-ingest` / this skill’s staging step).

## Repo resolution order

Resolve the repo target in this order:
1. if the user explicitly passes a repo path, use it as an override
2. otherwise use `repo_sync.repo_path` from the active profile
3. if the path is relative, resolve it relative to the wiki workspace root
4. verify the resolved path exists and is a git repository
5. resolve `repo_remote`, `default_branch`, `provider`, and `repo_slug` from the active profile
6. if any of these are absent, fall back conservatively to repo-local discovery where possible

Validation checks:
- repo path exists
- `.git/` exists or `git rev-parse --show-toplevel` succeeds in that path
- the configured remote exists, or `origin` exists when used as fallback
- the configured default branch exists locally or remotely after fetch

If validation fails, stop and report exactly which repo binding field is missing or invalid.

## Repo access and auth detection

The repo-backed wiki workflow must support both:
- local git inspection
- richer GitHub metadata when available

Preferred detection order:
1. local git access is the baseline and should always be attempted first
2. if `provider: github`, check whether `gh` is installed and authenticated
3. if `gh` is unavailable, continue with git-only inspection
4. if curl/token-based GitHub API access exists, it may be used, but it should improve awareness rather than become required for correctness

Recommended checks:

```bash
git --version
git -C "$REPO_PATH" rev-parse --show-toplevel
git -C "$REPO_PATH" remote get-url "$REPO_REMOTE"

gh --version 2>/dev/null || true
gh auth status 2>/dev/null || true
```

Interpretation:
- if local git works, repo sync can still proceed in git-only mode
- if `gh auth status` works, GitHub PR/metadata awareness can be added
- if GitHub metadata is unavailable, mark the report as git-only

## Step-by-step procedure

### 1. Resolve repo binding and repo-change input
Determine the workspace root first.
Then resolve `repo_path` using the repo resolution order above.

The repo-change input may be one of:
- repo path
- changed file list
- commit hash
- commit range
- PR summary
- release note with changed paths
- no explicit input, meaning inspect the delta between `last_compiled_sha` and current default-branch head

Normalize the input into one of these concrete forms:
- changed file list
- commit range
- single commit
- provider-backed PR/change summary plus changed files

### 2. Fetch upstream state safely
Do not mutate the source repo beyond read-only refresh operations.
Use fetch, not merge or pull.

Recommended commands:

```bash
git -C "$REPO_PATH" fetch "$REPO_REMOTE" --prune
git -C "$REPO_PATH" rev-parse "$REPO_REMOTE/$DEFAULT_BRANCH"
git -C "$REPO_PATH" rev-parse HEAD
```

If `last_compiled_sha` exists in `.llm-wiki/manifest.json`, compare it to the latest default-branch head.

Recommended commands:

```bash
git -C "$REPO_PATH" diff --name-only "$LAST_COMPILED_SHA..$REPO_REMOTE/$DEFAULT_BRANCH"
git -C "$REPO_PATH" log --oneline "$LAST_COMPILED_SHA..$REPO_REMOTE/$DEFAULT_BRANCH"
```

If no `last_compiled_sha` exists yet:
- treat the run as an initial repo inspection
- use watched paths and authority buckets to keep the first staging pass conservative

### 3. Gather provider metadata when available
If `provider: github` and `repo_slug` is defined, attempt GitHub-aware inspection only as an enhancement.

Preferred path:

```bash
gh auth status
gh api "repos/$REPO_SLUG"
gh api "repos/$REPO_SLUG/pulls?state=open&per_page=20"
```

Use provider metadata for:
- open PR awareness
- clearer change summaries
- optional mapping of merged PRs to commit ranges

If provider access fails:
- retry transient failures a small number of times
- then continue with git-only inspection
- clearly mark the report as git-only

Do not fail the whole repo-sync operation merely because GitHub metadata is unavailable.

### 4. Normalize changed files or change units
Normalize the inspection into a concrete list of changed files or change units.

Typical commands:

```bash
git -C "$REPO_PATH" diff --name-only "$BASE_SHA..$TARGET_SHA"
git -C "$REPO_PATH" diff --stat "$BASE_SHA..$TARGET_SHA"
git -C "$REPO_PATH" show --name-only --stat "$COMMIT_SHA"
```

For PR-backed awareness, capture:
- PR number/title
- base/head refs
- changed files
- merge status when available

### 5. Classify each changed item using profile rules
For each changed file or change unit, determine:
- source kind
- authority level
- likely truth category, such as:
  - runtime behavior
  - config/manifest truth
  - maintained reference guidance
  - flow behavior
  - legacy documentation
  - product/brochure framing

Use the active profile's watched paths, authority buckets, and authority ranking whenever possible.

Recommended rule:
- if a file matches no watched path, keep it in the report but classify it conservatively as lower-confidence impact unless there is clear evidence otherwise

### 6. Map likely affected wiki pages
Using the active profile's impact map, predict likely affected wiki page types or concrete pages.
Keep the candidate list conservative and targeted.

Examples:
- config/manifests → services, editions, maps, comparisons, queries
- flow changes → flows, comparisons, queries
- runtime file changes → service pages, concepts, maps
- security docs → security pages and high-level query/comparison pages

### 7. Stage the repo changes
Stage each change via `lw-ingest` behavior into:
- `raw/repo/` for direct repo files
- `raw/changes/` for diffs, commit ranges, PR summaries, release notes

When staging direct repo files, preserve enough path context to map back to the source repo.
When staging change summaries, include:
- repo path
- remote
- default branch
- base SHA
- target SHA
- provider-backed or git-only mode

Update `.llm-wiki/manifest.json` with:
- `last_checked_at`
- `last_seen_default_branch_sha`
- `last_repo_summary`
- `pending_changes`
- any staged artifact registrations

Do not mutate `wiki/` directly in this skill.

### 8. Decide what should happen next
Based on the authority and breadth of change, recommend or trigger:
- `/lw-compile` when there are real wiki impacts
- `/lw-lint` when changes are structural, broad, or high-authority
- `/lw-reflect` when changes are cross-cutting or likely to create synthesis/contradiction opportunities

Recommended boundary:
- `lw-sync-repo` inspects, classifies, stages, and updates manifest state
- orchestrator/operator decides whether to continue into compile/lint/reflect immediately

### 9. Print a repo-sync summary
Return:
- resolved repo path
- remote and default branch used
- provider mode used: provider-backed or git-only
- changed items reviewed
- authority classifications
- staged raw artifacts created
- likely affected wiki pages
- next recommended lifecycle steps

## Hard rules
- do not assume every repo change deserves a customer-facing wiki change
- prioritize maintained truth sources over noisy or weaker sources
- if impact is ambiguous, preserve contradiction-friendly handling instead of forcing a clean story
- do not skip staging and manifest registration
- do not mutate the source repo beyond read-only inspection operations such as fetch
- do not let missing GitHub metadata block git-based inspection when the local repo is available