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

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: summary (single summary record)"

If grouped (6-20), show the proposed theme groupings with commit lists per group.

Ask (using AskUserQuestion):

"Generate catch-up records for [N] untracked commits?"

1. Yes, generate -- Proceed with proposed batching
2. Adjust groupings -- Modify theme groups (split, merge, rename)
3. Exclude some commits -- Deselect specific commits from the list
4. Cancel -- Exit without generating records

If the user chooses option 2 (Adjust groupings), present the groups and allow modifications, then re-ask the question. If the user chooses option 3 (Exclude some commits), show the commit list and let the user deselect, then re-ask with updated count.

---

Step 5: Generate CATCHUP_ Records

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-catch-up/references/catchup-record-format.md for the record format specification.

Read CATCHUP_REPORT_TEMPLATE.json from the template path configured in ## Arness (field: Template path). If the template is not found in the project template directory, fall back to the plugin default at ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/report-templates/default/CATCHUP_REPORT_TEMPLATE.json.

For each record (individual, grouped, or summary):

1. Create the directory:

   mkdir -p <plans-dir>/CATCHUP_<name>/
   

2. Generate CHANGE_RECORD.json using the template with the catchup extension object:

   • Set ceremonyTier to "catchup"
   • Populate filesModified and filesCreated from git diff-tree output
   • Set commitHash to the commit hash (individual) or the latest commit hash in the group
   • Set commitMessage to the commit message (individual) or a generated group summary
   • Populate catchup.coveredCommits with all commit hashes covered by this record
   • Populate catchup.scanRange with the scan window and detection method
   • Always set catchup.confidence to "low"
   • Populate catchup.gaps honestly -- list what information is missing
   • Populate catchup.whatWeKnow from git data (files changed, commit message, diff stats)
   • Populate catchup.whatWeDontKnow with standard unknowns (intent, test coverage, architectural reasoning)

3. Generate CATCHUP_<name>.md markdown summary using the "What We Know / What We Don't Know" framing as specified in the record format reference.

4. Always set confidence: "low". Populate gaps[] honestly. Do not fabricate intent or reasoning -- only document what git data can prove.

If pre-Arness commits were detected, generate a boundary marker record:

• Directory: <plans-dir>/CATCHUP_pre-arness-boundary/
• CHANGE_RECORD.json with catchup.boundaryMarker: true
• CATCHUP_pre-arness-boundary.md boundary marker markdown

Display:

Generated <N> catch-up record(s) in <plans-dir>/:
  CATCHUP_<name1>/
  CATCHUP_<name2>/
  ...

---

Step 6: Pattern Refresh (Conditional)

Check if any of the untracked commits modified files that are referenced in the pattern documentation (code-patterns.md, testing-patterns.md, architecture.md, ui-patterns.md).

To check: extract the file paths from each untracked commit using git diff-tree --no-commit-id --name-only -r <hash>. Compare these paths against the "Reference" fields in the pattern documentation files.

If pattern-relevant files were modified:

Ask (using AskUserQuestion):

"Untracked commits modified files referenced in your pattern documentation. Refresh pattern docs now?"

Options:

1. Yes, refresh patterns -- Run the pattern refresh procedure
2. No, skip -- Keep current patterns as-is

If Yes:

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-execute-plan/references/pattern-refresh.md and follow the pattern refresh procedure.

If No: skip silently.

If no pattern-relevant files were modified, skip this step silently (no message needed).

---

Step 7: Completion Summary

Display the final summary:

Catch-Up Complete
=================
Records generated:   <N> individual / <N> groups / 1 summary
Boundary marker:     yes / no
Pattern refresh:     performed / skipped
Commits now tracked: <N> (of <N> total untracked)

Offer next steps:

Run `/arn-code-ship` to commit the catch-up records.

Note:

Run `/arn-code-catch-up` again after more out-of-pipeline commits -- it's idempotent and won't create duplicates.

---

Error Handling

• Git not available -- inform user: "This project is not a git repository. /arn-code-catch-up requires Git." and exit.
• Plans directory missing -- inform user: "Plans directory not found. Run /arn-planning to set up Arness." and exit.
• No commits in scan range -- inform user: "No commits found in the scan range ( to HEAD)." and exit.
• All commits tracked -- inform user: "All commits in the scan range are already tracked by Arness artifacts. Nothing to catch up on." and exit.
• Git log command fails -- display the error, suggest checking git configuration.
• CHANGE_RECORD.json parse error -- warn about the malformed file, skip it, continue with remaining files.
• Template not found -- fall back to plugin default template. If that also fails, generate records without the template (use the record format reference as the schema).