Skip to content

Pipeline Design 190

Jump to bottom
Seth Ford edited this page Mar 1, 2026 · 1 revision

Design: Stale documentation detected

Context

The shipwright docs check system detected stale AUTO sections in .claude/CLAUDE.md. AUTO sections are HTML-comment-delimited blocks (<!-- AUTO:section-id --> ... <!-- /AUTO:section-id -->) that are regenerated from source code. The core-scripts section drifted because two scripts changed line counts after recent edits:

  • scripts/sw-intelligence.sh: 1547 → 1523 (24 lines removed)
  • scripts/sw-pipeline.sh: 2944 → 2883 (61 lines removed)

The fix has already been applied by shipwright docs sync. This is a pure documentation synchronization — no runtime behavior, no API contracts, no new dependencies.

Decision

Apply the already-generated docs sync output as-is. The change is confined to a single file (.claude/CLAUDE.md) updating two numeric values in the core-scripts AUTO table. No architectural changes are needed. The existing documentation keeper infrastructure (sw-docs.sh) correctly detected and fixed the drift.

Pattern used: Existing AUTO-sync pipeline — source-of-truth is the script files on disk, wc -l generates the canonical line counts, and docs sync rewrites the markdown table rows.

Alternatives Considered

  1. Manual edit of line counts — Pros: Fastest possible fix / Cons: Error-prone, bypasses the sync tooling that exists precisely for this purpose. Rejected because it undermines the automation.

  2. Suppress the staleness signal — Pros: No commit needed / Cons: Leaves documentation inaccurate, erodes trust in AUTO sections, and the daemon patrol would re-flag it. Rejected because stale docs are a real problem for agents that consume CLAUDE.md as context.

Implementation Plan

  • Files to create: none
  • Files to modify: .claude/CLAUDE.md (already modified by docs sync — two line count values in the core-scripts AUTO table)
  • Dependencies: none
  • Risk areas: none — this is a data-only change in a markdown table with no runtime impact

Validation Criteria

  • shipwright docs check exits 0 (all 6 AUTO sections fresh)
  • npm test passes (no test regressions from doc-only change)
  • git diff shows only line count changes in the core-scripts table for sw-intelligence.sh and sw-pipeline.sh

Clone this wiki locally