sync-findings

# Sync Findings

Read these shared references when needed:

- `../shared/references/findings.schema.md`
- `../shared/references/findings.lifecycle.md`

## Role

Keep the active findings record aligned with current local state and, when requested, current GitHub PR state.

- Pull in open PR comments, review notes, local review docs, and current code state.
- Map comments to findings, update sources and statuses, and surface follow-up questions.
- When GitHub thread operations are available, reply to and resolve threads that are clearly closed by current findings.

## URL Input

Accept an optional GitHub PR `url` from the prompt.

- If a PR URL is provided, do remote plus local sync.
- If no URL is provided, do local-only sync.

Default:

- `url=local-only`

## Path Input

Accept an optional `path` from the prompt.

- If `path` is provided, use it as the local design or findings folder.
- If `path` is omitted, infer it from the branch, subsystem, or matching docs and state the inferred value before starting.

Default:

- `path=infer`

## Workflow

1. Establish sync scope.
   Confirm the effective variables first:
   - `path`
   - `url`
   - branch, PR URL if present, and any requested focus areas

2. Load the active findings record.
   Use `path/findings.md`.

3. **SAVE FIRST — write every new finding into `path/findings.md` before doing anything else.**
   This is the non-negotiable first action of every sync. Before proposing fixes, discussing implications, replying to threads, or updating any other doc:
   - For each new PR review comment or scan observation, add an entry under `## Open Findings` using the canonical schema (ID, severity, files, evidence, decision pending).
   - Mark every new finding as `needs-user-decision` unless the user has already given direction.
   - Refresh the `## Summary` section so the latest state is visible at the top.
   - Only after `findings.md` is up to date may you start summarizing for the user or proposing fixes.

   This rule exists because diving straight into "let me explain / propose / fix" mode loses context and leaves the user to reconstruct the finding list themselves. The doc is the source of truth, not the chat history.

4. Sync sources into findings.
   Re-check existing findings against current local code and docs.
   If `url` is present, pull open PR comments and thread state into the same record.

5. Ask clarifying questions before parking ambiguity.
   If a finding's disposition or intended action is still unclear, ask the next concrete question instead of silently leaving it vague.

6. Close only what is clearly closed.
   When a GitHub thread maps to a closed finding, leave a short reply with the finding ID when relevant and resolve the thread.
   Leave still-open or still-ambiguous threads untouched.

## Rules

- **Save-first is mandatory.** Step 3 must complete before any code change, fix proposal, GitHub reply, or summary update. No exceptions.
- Sync is not a substitute for execution planning; use `triage-findings` when the user needs help deciding what to do next.
- Do not silently drop sources, thread IDs, or comment provenance.