Skip to content

Add 6 anti-patterns to research-documentation workstream (14-19) - #5

Merged
rmsharp merged 2 commits into
mainfrom
feature/research-doc-anti-patterns-14-19
Apr 26, 2026
Merged

rmsharp merged 2 commits into
mainfrom
feature/research-doc-anti-patterns-14-19

Conversation

@rmsharp

@rmsharp rmsharp commented Apr 26, 2026

Copy link
Copy Markdown
Owner

Summary

Adds anti-patterns 14–19 to workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md, surfaced during an editorial audit of a 16-paper, ~5,930-line research-documentation corpus that applied this workstream's Audit Mode. Each new pattern is grounded in concrete findings from that audit; none overlap the existing 13.

The new anti-patterns

# Name Distinct from
14 Companion-paper drift — extracts diverge from sources over time KJ5HST#9 (edit from memory, within-session) — this drift is across-time
15 Stale verification artifact — verification reports lose coverage as targets evolve (new dimension — no overlap)
16 Date-anchored prose without timestamp — "as of early 2025" silently ages #1 (citation drift) — this is narrative tense, not citation keys
17 Multiple-bibliography drift — per-cluster .bib files diverge from canonical (names the failure of the existing Phase 3 "single bibliography" rule)
18 Verification-flag / body-text divergence — flag exists but doesn't propagate to body #6 (descriptive-page substitution) — the source-quality issue is identified, it just doesn't reach the body
19 Scope-overlap silence between sibling papers — papers share evidence with no cross-reference KJ5HST#12 (redundant restatement) — this is across-paper, between artifacts that consciously chose to be separate

Format

Each addition follows the same "name — symptom — mitigation" form as the existing 13. The Audit Mode "Severity calibration" table (Critical/Moderate/Minor) is updated to reference the new anti-patterns by number.

Provenance

The originating audit is preserved in the project where the patterns were observed: rmsharp/model_governance:docs/audits/20260425_qmd_corpus_audit.qmd. That audit produced 55 findings across 16 papers; the 6 patterns proposed here each had multiple supporting findings in that report. References to specific findings are in the local commit message.

Test plan

  • Markdown renders cleanly (no broken table syntax)
  • Anti-pattern numbering is contiguous (1–19)
  • Severity calibration table references all 6 new anti-patterns by number
  • No regression to the existing 13 anti-patterns or to other sections

rmsharp and others added 2 commits April 25, 2026 20:03
Anti-patterns 14-19 surfaced during an editorial audit of a 16-paper, ~5,930-line
research-documentation corpus that applied the workstream's Audit Mode. Each is
grounded in concrete findings from that audit; the audit report is preserved in
the originating project (rmsharp/model_governance:docs/audits/20260425_qmd_corpus_audit.qmd).

Each new anti-pattern is in the same "name — symptom — mitigation" form as the
existing 13. None overlap the existing list:

14. Companion-paper drift — extracts diverge from sources over time. Distinct
    from KJ5HST#9 (edit from memory, within-session); this drift is across-time.

15. Stale verification artifact — verification reports and pending-changes
    documents lose coverage as their target documents accumulate new content.

16. Date-anchored prose without timestamp — phrases like "as of early 2025"
    silently age. Distinct from #1 (citation drift); this is narrative tense.

17. Multiple-bibliography drift — per-cluster .bib files diverge from the
    canonical project bibliography. Names the failure of the existing Phase 3
    "use a single bibliography" rule.

18. Verification-flag / body-text divergence — a claim is correctly flagged in
    Verification Flags but the body text presents it without caveat. Distinct
    from #6 (descriptive-page substitution); the flag exists, it just doesn't
    propagate to the body.

19. Scope-overlap silence between sibling papers — two papers share evidence
    with no cross-reference. Distinct from KJ5HST#12 (redundant restatement,
    within-paper); this is across-paper.

The Audit Mode "Severity calibration" table (Critical/Moderate/Minor) is
updated to reference the new anti-patterns by number.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Audit Mode "Map this workstream's machinery into audit deliverables"
table referenced "The 13 anti-patterns" — a stale count from before this
PR added patterns 14-19. Update to "The 19 anti-patterns" to match the
new total.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rmsharp

rmsharp commented Apr 26, 2026

Copy link
Copy Markdown
Owner Author

Closing — work landed directly on main as commits 557a89e (add 6 anti-patterns) and 6d9833e (fix anti-pattern count in audit-mode mapping table). The PR was bypassed in favor of a direct merge.

@rmsharp rmsharp closed this Apr 26, 2026
@rmsharp
rmsharp deleted the feature/research-doc-anti-patterns-14-19 branch April 26, 2026 03:26
@rmsharp
rmsharp restored the feature/research-doc-anti-patterns-14-19 branch April 26, 2026 04:25
@rmsharp rmsharp reopened this Apr 26, 2026
@rmsharp
rmsharp merged commit e376226 into main Apr 26, 2026
rmsharp added a commit that referenced this pull request May 8, 2026
PR #5 added anti-patterns 14-19 to RESEARCH_DOCUMENTATION_WORKSTREAM.md but
left the version-summary text in CLAUDE.md and README.md saying "13", causing
the v2.3 What's New section to undercount the workstream's actual content.
The Audit Mode bullet on README also referenced "the 13 anti-patterns as
finding categories" — same drift. Fix both in CLAUDE.md and the two README
occurrences.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rmsharp added a commit that referenced this pull request May 12, 2026
Brings in KJ5HST/main's 4ec14c6 — the v2.3 content release from issue KJ5HST#7
(rad-con SESSION_RUNNER audit). Auto-merged starter-kit/SESSION_RUNNER.md
(new Phase 3E Runtime Smoke Test, FM KJ5HST#24 appended, Phase 1B "structural
control" line, Planning Sessions grep anecdote, 5 new Learnings rows).

Conflicts resolved in CLAUDE.md and README.md:

- Kept local "Current version: v2.4" line (upstream is at v2.3).
- Combined the two v2.3 entries into one, mirroring the wording PR KJ5HST#9
  already reviewed by KJ5HST: contribution (1) Research Documentation
  workstream with 19 anti-patterns (post-PR-#5 count); contribution
  (2) SESSION_RUNNER content release from rad-con audit.
- README.md uses two sub-headings under "What's New in v2.3"
  (Research Documentation workstream / SESSION_RUNNER content release).
- Local v2.4 "What's New" section preserved above v2.3.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rmsharp pushed a commit that referenced this pull request May 25, 2026
…e notes

Addresses self-review findings #4 and #5.

#4 — CLAUDE.md's v2.6 entry omitted the Phase 3F / Phase 6 step 8
debug-cleanup gate. README's entry already named it; the two notes now
match. Inserted next to FM KJ5HST#25 since both ship in SESSION_RUNNER.

#5 — Both CLAUDE.md and README's v2.6 entries previously claimed
"single Phase 2 cross-reference in HOW_TO_USE.md cites by name; safe."
HOW_TO_USE.md actually has ~10 mentions of "Phase 2" — true in spirit
because none reference numbered steps within Phase 2, but the
"single" framing is wrong. Reworded to: "Phase 2 cross-references in
HOW_TO_USE.md all cite by name, never by step number, so the
renumber is safe."
@rmsharp
rmsharp deleted the feature/research-doc-anti-patterns-14-19 branch June 19, 2026 20:03
rmsharp added a commit that referenced this pull request Jul 8, 2026
…GELOG-ledger campaign (S7, D1)

Ships .githooks/pre-commit — the mechanical enforcement of FM KJ5HST#27 where a
repo has no root SESSION_RUNNER to run the close-out gate (escape #5): it
refuses a commit that changes tracked content unless CHANGELOG.md is
co-staged. Deliberately narrow and bypassable: skips merges/rebases and
absent-ledger repos, `git commit --no-verify` bypasses it, and Phase 0
reconcile-on-read (Component B) is the guarantee that backfills anything
past it. Match is fixed-string (grep -qxF), not a regex.

Docs: SAFEGUARDS Commit Discipline "Ledger Co-Staging Hook" subsection;
BOOTSTRAP Step 10 setup paragraph + scoped the stale "does not ship its
own hook script" line to blast-radius only; BOOTSTRAP First Session
Checklist step 7 gains the ledger step (escape KJ5HST#8, same class).

CHANGELOG.md: campaign S2-S7 marked complete. This commit is gated by the
hook it ships and passes (CHANGELOG co-staged) — the dogfood.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant