/arn-code-catch-up

name: arn-code-catch-up
description: >-
  This skill should be used when the user says "catch up", "catch-up",
  "arness code catch up", "retroactive docs", "document old commits",
  "backfill artifacts", "what did I miss", "undocumented commits",
  "catch up on commits", "document past work", "backfill records",
  or wants to retroactively document commits that were made outside the Arness pipeline.
version: 1.0.0
argument-hint: "[since-date-or-commit]"

Arness Catch-Up

Developers sometimes bypass the pipeline for quick fixes -- the "2am gap." These commits ship without specs, plans, or records, leaving holes in the artifact trail. Catch-up scans git history, identifies commits that have no corresponding Arness artifacts, and generates lightweight CATCHUP_ records in the CHANGE_RECORD.json envelope. The records are honest about what can and cannot be recovered retroactively: they document what changed (files, diffs, commit messages) and explicitly flag what is unknown (intent, test coverage, architectural reasoning).

This is a standalone skill. It operates outside the main pipeline and can be run at any time.

---

Step 0: Ensure Configuration

Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md` and follow its instructions. This guarantees a user profile exists and `## Arness` is configured with Arness Code fields before proceeding.

---

Step 1: Load Configuration

Read the `## Arness` section from CLAUDE.md. Extract the following fields:

• **Plans directory** -- where Arness project artifacts live (CHANGE_RECORD.json files, SWIFT_*, STANDARD_*, CATCHUP_* directories)
• **Specs directory** -- where spec files live (for boundary detection)
• **Code patterns** -- path to pattern documentation (for pattern refresh in Step 6)
• **Template path** -- path to report templates (for CATCHUP_REPORT_TEMPLATE.json)
• **Template version** -- plugin version the templates were copied from (if present)
• **Template updates** -- user preference: `ask`, `auto`, or `manual` (if present)

**Template version check:** If `Template version` and `Template updates` fields are present, run the template version check procedure documented in `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/references/template-versioning.md` before proceeding. If `## Arness` does not contain these fields, treat as legacy and skip.

Validate that all paths exist. If the plans directory does not exist, inform the user: "Plans directory not found. Run `/arn-planning` to set up Arness." and exit.

---

Step 2: Determine Scan Range

Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-catch-up/references/cross-reference-algorithm.md` for the scan range detection procedure.

Execute the three-tier fallback:

1. Search git log for the most recent commit with a `[swift]`, `[standard]`, `[thorough]`, or `[catchup]` tier tag. 2. If not found, read `PROGRESS_TRACKER.json` files in the plans directory and use the most recent `lastUpdated` timestamp. 3. If neither found, use 30 days before the current date.

Display:

Scanning commits from <date> to HEAD (<N> commits in range).
Scan range determined by: <method> (tier-tag commit | progress tracker | 30-day default)

Offer override:

Adjust scan range? (Enter a date or commit hash, or press Enter to continue)

If the user provides a date or commit hash, adjust the scan start accordingly.

---

Step 3: Cross-Reference and Identify Untracked Commits

Follow the cross-reference algorithm from `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-catch-up/references/cross-reference-algorithm.md`.

Execute these steps in order:

1. **Collect commits:** Run `git log --format='%H|%aI|%s' --no-merges --after=<scan-start>` to get all commits in range. Validate commit hashes as 40-character hex strings.

2. **Primary match:** Scan all `CHANGE_RECORD.json` files in the plans directory. Extract `commitHash` fields. Mark any commit whose hash appears in a CHANGE_RECORD as "tracked".

3. **Secondary match -- tier tags:** If a commit message contains `[swift]`, `[standard]`, `[thorough]`, or `[catchup]`, mark as "tracked".

4. **Secondary match -- file overlap:** For remaining unmatched commits, run `git diff-tree --no-commit-id --name-only -r <hash>` to get modified files. Compare against `filesModified` and `filesCreated` arrays in CHANGE_RECORD.json files. If >80% file overlap with any CHANGE_RECORD, mark as "likely tracked".

5. **Report file scanning:** Check if any `IMPLEMENTATION_REPORT_*.json` or `TESTING_REPORT_*.json` files reference the commit hash.

6. **Idempotency check:** Scan existing CATCHUP_ CHANGE_RECORD.json files for `catchup.coveredCommits` arrays. Exclude any commit whose hash already appears in a previous catch-up record.

7. **Boundary detection:** Identify commits whose dates precede the earliest Arness artifact. Classify these as "pre-Arness".

Classify each commit as one of:

• **tracked** -- matched to an existing Arness artifact
• **likely tracked** -- high file overlap with an existing artifact (needs user confirmation)
• **untracked** -- no match found
• **pre-Arness** -- predates the earliest Arness artifact

---

Step 4: Present Overview and Confirm

Display the findings:

Scan Results
============
Total commits in scan range:           <N>
Tracked (matched to Arness artifacts):   <N>
Likely tracked (file overlap match):   <N>
Untracked:                             <N>
Pre-Arness (predates earliest artifact): <N>

If there are "likely tracked" commits, list them for manual confirmation:

The following commits have >80% file overlap with existing artifacts:
  <short-hash> <message> -- overlaps with <CHANGE_RECORD path>
  ...
Mark these as tracked? (They will be excluded from catch-up records if confirmed.)

Display the proposed batching tier:

• 1-5 untracked: "Batching: **individual** (one record per commit)"
• 6-20 untracked: "Batching: **grouped** (commits clustered by theme)"
• 21+ untracked: "Batching