Skip to content

feat: add research documentation workstream (v2.2) - #4

Merged
rmsharp merged 3 commits into
mainfrom
feature/research-documentation-workstream
Apr 25, 2026
Merged

feat: add research documentation workstream (v2.2)#4
rmsharp merged 3 commits into
mainfrom
feature/research-documentation-workstream

Conversation

@rmsharp

@rmsharp rmsharp commented Apr 25, 2026

Copy link
Copy Markdown
Owner

Summary

  • New workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md — adapts the methodology for research papers, technical reports, dissertations, and regulatory analyses where claims must trace to cited primary sources
  • Patterns extracted from a real-world Quarto-based 8-dimension synthesis project (Phases A–G); 10 named learnings absorbed into Phase 2 (Research) and Phase 6 (Verify & Close)
  • 13 documented anti-patterns, 6-toolchain adaptation table (Quarto/LaTeX/Sphinx/Pandoc/AsciiDoc/Markdown), and a "Recommended Operating Mode" callout (deepest-reasoning settings; sloppy research damages trust more than missing research does)
  • Cross-reference updates across CLAUDE.md, README.md, HOW_TO_USE.md, ITERATIVE_METHODOLOGY.md, starter-kit/SESSION_RUNNER.md, starter-kit/BOOTSTRAP.md; version bumped to v2.2

What the workstream adds

Concept Where it lives
Source corpus inventory + filename verification Phase 2, Steps 2 & 5
WAF retrieval hierarchy (curl → WebFetch → browser UA → Wayback → user) Phase 2, Step 4
Pre-flag completeness audit + post-hoc dedup Phase 2, Step 3
Claim-source map (≤40-word quoted passage per claim) Phase 3 + Phase 6
Audit-failed-but-true escalation Phase 6 Claim-Source Audit
Sub-agent permission asymmetry pattern Phase 6 dedicated subsection
Verify-before-destroy Phase 6 Cleanup
Render verification across PDF/HTML/DOCX targets Phase 6 Render Verification

Test plan

  • Workstream document renders cleanly in GitHub markdown preview (no broken tables, code fences, or links)
  • Cross-reference updates show the new workstream in the right context across the 6 modified files (workstream tables, directory trees, task-to-workstream mapping)
  • Version bump (v2.1 → v2.2) is consistent across CLAUDE.md and README.md's "What's New" section
  • Workstream picks up cleanly when adopted by a new research-documentation project (smoke test in next session)

🤖 Generated with Claude Code

rmsharp and others added 2 commits April 24, 2026 23:23
@rmsharp @claude
feat: add research documentation workstream (v2.2)
2bb0376 
Adds workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md to adapt the
methodology for research papers, technical reports, dissertations, and
regulatory analyses where claims must trace to cited primary sources.

Patterns extracted from a real-world Quarto-based research-documentation
project (8-dimension model-governance synthesis, Phases A-G):

- Source-corpus management: pre-flag completeness audit, WAF retrieval
  hierarchy (curl -> WebFetch -> browser UA -> Wayback -> user browser),
  filename-content verification, post-hoc dedup including pre-existing
  corpus
- Claim-source audit pattern: every numeric/dated/attributed claim
  requires a quoted passage (<=40 words) from a primary source; baseline
  ~22% unsupported / ~12% re-attribution rate from real-world use
- 13 documented anti-patterns including citation drift, filename trust,
  premature delete on audit-flagged claims/files, sub-agent permission
  asymmetry, and goal-language for constraints
- 6-toolchain adaptation table: Quarto, LaTeX, Sphinx, Pandoc, AsciiDoc,
  Markdown
- Recommended Operating Mode callout: workstream benefits materially
  from deepest-reasoning agent settings because documentation errors
  surface as credible-looking citations that pass casual review

Cross-reference updates propagate the new workstream across CLAUDE.md
(workstream table, version bump to v2.2, history entry), README.md
(directory tree, workstream table, What's New in v2.2), HOW_TO_USE.md,
ITERATIVE_METHODOLOGY.md, starter-kit/SESSION_RUNNER.md (task-to-
workstream mapping), and starter-kit/BOOTSTRAP.md (directory tree).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rmsharp @claude
feat: add Audit Mode to research documentation workstream
b2a0815 
Adds an Audit Mode section to RESEARCH_DOCUMENTATION_WORKSTREAM.md
covering the use case of auditing an existing research-documentation
repository with fresh eyes, where the deliverable is a finding list
rather than modifications to the papers.

- New "When to Use" bullet for retrospective examination
- Updated "Distinct from the Audit workstream" paragraph to describe
  the relationship between AUDIT_WORKSTREAM and this workstream's
  Audit Mode
- New Audit Mode section between Recommended Operating Mode and
  Phase 2, mapping this workstream's procedures into review-session
  deliverables (per AUDIT_WORKSTREAM Phase 1-4 pattern, skipping
  Phase 5)
- Audit report structure template, severity calibration table,
  and a scoping heuristic (>40 critical findings -> split by paper
  or dimension)
- README "What's New in v2.2" updated with Audit Mode bullet

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rmsharp added a commit that referenced this pull request Apr 25, 2026
@rmsharp
feat: add CHANGELOG/ROADMAP templates and three-file task tracking (#4)
274dcd4 
Adds CHANGELOG.md and ROADMAP.md templates to the starter kit, splitting task tracking into three focused files: BACKLOG.md (open work only), CHANGELOG.md (completed work history), ROADMAP.md (feature inventory and future plans). Includes migration guide in BOOTSTRAP.md for projects with existing monolithic backlogs, dashboard compliance updates (6→8 required items), and v2.1 version bump.
rmsharp added a commit that referenced this pull request Apr 25, 2026
@rmsharp
fix: correct collect_coverage_config() logic bugs and add recursive s…
c624eeb 
…canning (#5)

Rewrites collect_coverage_config() with recursive scanning and fixes from PR #3/#4 review: drops pytest-cov from JS package.json check, replaces ambiguous "coverage" with specific packages (c8, @vitest/coverage-v8, @vitest/coverage-istanbul), adds fallback for unknown @vitest/coverage-* variants, explicit if/elif instead of hostile operator precedence. Also adds .claude to WALK_SKIP, vite.config.* detection with content sniffing, and requirements.txt pytest-cov check.
@rmsharp @claude
Merge main into feature/research-documentation-workstream
1bd4fe8 
Incorporates upstream KJ5HST v2.2 (bin/sync, bin/status, CLAUDE_TEMPLATE,
BOOTSTRAP rewrite) into the research-documentation workstream branch.

Conflict resolutions:
- CLAUDE.md: keep upstream's expanded v2.1 + v2.2 entries; renumber our
  workstream addition from v2.2 to v2.3 (our v2.2 collided with
  upstream's v2.2 release)
- README.md: keep upstream's v2.2 What's New section; move our content
  to a new v2.3 section above
- starter-kit/BOOTSTRAP.md: take upstream's rewritten version
  (supersedes our 1-line directory tree addition; the workstream is
  documented elsewhere via README, CLAUDE.md, ITERATIVE_METHODOLOGY,
  and SESSION_RUNNER mapping)
- HOW_TO_USE.md and starter-kit/SESSION_RUNNER.md: clean auto-merge

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rmsharp
rmsharp merged commit 987612c into main Apr 25, 2026
rmsharp pushed a commit that referenced this pull request May 4, 2026
KJ5HST @claude
docs: v2.3 content release — 6 upstream candidates from rad-con audit (…
4ec14c6 
…KJ5HST#7)

Issue KJ5HST#7 distilled 6 universal additions from a 90-session field audit of
rad-con/SESSION_RUNNER.md. All approved by community feedback (rmsharp), with
one wording revision to Learnings row #4.

starter-kit/SESSION_RUNNER.md changes:
- Phase 1B: added "structural control, not a suggestion" line
- Planning Sessions: added concrete grep anecdote (10+ refs, 2 greps)
- New Phase 3E: Runtime Smoke Test — old 3E (Commit) → 3F, old 3F (Report) → 3G
- FM KJ5HST#24 APPENDED: Build-passes-ship-it — FMs 1–23 unchanged
- Degradation Detection: row added for FM KJ5HST#24
- Learnings: 5 new rows (#2–#6)

Row #4 wording: rmsharp flagged that "high-quality plans collapse multi-session
work into a single session" reads as license to bend "1 and done." Reframed
to put completion-criteria verification first and explicitly state that the
rule does not bend for high-quality plans. The original lesson (verify by
criteria, not by clock) survives; the erosion-bait headline is removed.

Backward compatibility: FMs 1–23 not renumbered. Only "Phase 3E Commit" →
"Phase 3F Commit" — adopters citing phase numbers in memory should update.

Open coordination: PR KJ5HST#9 also claims v2.3 in file edits. Either KJ5HST#9 rebases
to v2.4, or both fold into a single v2.3 release before tagging.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rmsharp pushed a commit that referenced this pull request May 25, 2026
KJ5HST
fix: add Phase 3F gate + tighten cross-reference claim in v2.6 releas…
aeff4bc 
…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 added a commit that referenced this pull request Sep 5, 2026
@rmsharp @claude
docs(handoffs): S95 close-out — self-score 8/10, predecessor S94 scor…
92519cd 
…ed 9/10

CHANGELOG.md 84,765 B -> 31,539 B (-62.8%), under both the 65,536 B ceiling and
the seed's <= 1/2 x budget stop condition. The frozen proof passes.

Also: Framework Learning KJ5HST#32 — a count-based cut cannot see a content-population
floor, and whether it trips is a fact about the data's layout, not an invariant.
Test 30 requires a non-empty **Model:** population in the live ledger; the only
carriers were records #4 and KJ5HST#13 of 41. The tool's dry run reports bytes and
counts, the exact quantities such a floor is invisible to.

Suite 235/1, row-for-row against a full baseline: zero rows lost, three changed,
all explained.

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@rmsharp