docs(guides): apply Adopter #2 friction fixes to spec-digest-pattern - #198
Merged
Conversation
Closes 6 of 7 items from issue #197 (Adopter #2 report from claude-all/netbird-sit, ops/infra archetype). Item 4 architectural fix split to pitimon/claude-governance#34. Fixes: - §3 (Live backlog) — define "stale" threshold explicitly as "exists in canonical form elsewhere", not "more than N days old". Day-1 deletion rule prevents §3 from drifting into a done-list (item 3) - §4 verification — replace `grep -A1` with awk range scan (robust against blank-line-after-heading per markdownlint MD022) (item 2.1) - §4 verification — add companion grep for backtick-wrapped paths (template default; the existing markdown-link grep was the only one shipped) with `/`-prefix carve-out for ops repos referencing remote paths (item 2.2) - §1 template — explicit "one path per bullet" guidance; comma-listed siblings defeat the verification grep (item 2.3) - CLAUDE.md recipe step 3 — generalize from "data contracts" (feature-spec language) to "pointer-target file from §1 if any operational fact changed" (covers data contracts, runbooks, server state, changelog — whatever the §1 pointers actually reference) (item 5) - NEW section "Adopting alongside doc-blocker hooks" — stop-gap guidance for adopters whose repo has a PreToolUse hook blocking `.md` operations. Names the Write-new vs Edit-tracked conflation, cross-references the architectural fix tracked in pitimon/claude-governance#34 (item 4(c)) Validator state: validate-structure.sh 256/256 PASS; validate-content.sh 216 PASS / 0 FAIL / 1 WARN / 0 fitness breaches. Caught one self-induced Check 12b false-positive locally (markdown-link example in a code comment); fixed before push. Refs #197
This was referenced May 17, 2026
pitimon
added a commit
that referenced
this pull request
May 17, 2026
…202) Patch release. Adopter #2 dogfood pass on v2.16.0 /save-spec surfaced 1 correctness bug + 3 quality items — all four fixed in this PR. Closes #201. N1 (MEDIUM bug, fixed): §1 empty stub used `<filename>.md` which Check 4's backtick-path grep extracted as <filename>.md (literal angle brackets), failing [ -e ] and emitting MISS — Definition of Done's "passes 5 verification commands" claim was provably false on the default scaffold. Stub now uses plain prose with no backticked .md path. N2 (LOW, documented): Timestamp reliability profile documented in reference.md. The skill (no Bash) substitutes the Last updated value from Claude's session- injected <system-reminder>Current:</system-reminder> context; when absent the output may carry +00:00 or wrong offset. Adopter guidance: verify after scaffold, edit manually if wrong. Phase 2 hook for adding Bash if needed. N3 (LOW UX, fixed): Q2 now accepts "Other (free-text)" newline-separated paths for ops/infra repos with non-canonical naming (server-state.md, runbooks/, playbooks/, etc.). SKILL.md Process step 3 + 4 extended; reference.md Example F added. N4 (LOW doc, fixed): PRD FR-003 deduplicated — references reference.md Decision-3 as canonical (no paraphrased inline drift hazard). Validator state: validate-structure.sh 268/268 PASS, validate-content.sh 219+ PASS / 0 FAIL / 1 WARN / 0 fitness breaches. 8-habit-reviewer skipped — Adopter #2 wrote the review in #201; fixes match their suggested directions verbatim. Sibling closure: #197 now closeable (5/5 items addressed in v2.16.0 + #198). Refs #201, #197 Co-authored-by: itarun.p <itarun.p@somapait.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes 6 of 7 items from issue #197 — Adopter #2 report on the v2.15.9 spec-digest pattern from
claude-all/netbird-sit(ops/infra archetype). Item 4 architectural fix (PreToolUse hook should distinguish Write vs Edit on.mdfiles) is split to pitimon/claude-governance#34 — runtime enforcement belongs there per plugin boundary.Fixes
grep -A1false-negative on standard markdown blank-line-after-heading/-prefix carve-out for ops repos referencing remote pathsOut of scope (handled elsewhere)
/save-specskill —n≥2 adoptioncriterion is now met (netbox-sit + netbird-sit) and adoption-friction criterion has evidence (this PR). Scope-conflict criterion is implicitly resolved by Adopter feat(skills): add Definition of Done checklist to each workflow skill #2 ("both adopt project-orientation mode without using--persist; the two modes serve different repos"), but should be documented in writing before promotion. Defer to a follow-up issue.Test plan
validate-structure.sh256/256 PASSvalidate-content.sh216 PASS / 0 FAIL / 1 WARN / 0 fitness breaches (after fixing one self-induced Check 12b false-positive — a markdown-link example in a code comment, ironic given that's exactly what the user reported in item 2.2)Habit mapping
Refs #197, pitimon/claude-governance#34