docs(sdlc): promote 5 portable lessons from v1.76.0+v1.77.0 release arc#357
Merged
Conversation
After-Session memory audit captures gotchas that bit us today (or that would bite again if undocumented): 1. **gh pr merge --auto silently waits when branch is BEHIND.** No auto-rebase. Hit twice today (PR-B and PR-D both blocked behind a sibling merge that moved main). Fix: check mergeStateStatus after enabling --auto; rebase if BEHIND. 2. **State-change monitor loops must compare ONE prev string, not concatenated parts.** Our PR-B+PR-C monitor used 'cur \!= "$prev_a$prev_b"' which is string concat and always evaluates different. Caused repeated empty notifications. Fix: single prev variable, prev="$cur" after emit. 3. **Version-bump checklist: grep ALL 'SDLC Wizard Version' meta-comments.** The string lives in 6 places. Missing any one trips a different test. Caught at v1.76.0 (wizard doc template line ~2984) and v1.77.0 (update skill changelog example). Single command before tag: grep -rn the previous version. 4. **Self-managed CC install vs npm install coexist invisibly until 'which claude' differs from 'npm root -g'.** ~/.local/bin/claude (self-managed via install.sh) wins PATH over npm. 'npm i -g @anthropic-ai/claude-code@latest' silently updates a parallel install. Diagnosis: which claude vs ls /opt/homebrew/bin. Fix paths: 'claude update' for self-managed; or rm -rf ~/.local/share/claude to consolidate to npm. Also clean stale installMethod in ~/.claude.json. 5. **Negative-feature-existence claims need explicit citation.** LLM 'research' asserting feature X does NOT exist is easier to fake than 'X exists at <url>'. Twice in two sessions our claude-code-guide research asserted no native /goal when /goal had shipped in v2.1.139 weeks earlier. Rule: 'X doesn't exist' must cite the authoritative source the search ruled it out against. Each entry cites the originating PR or incident date per Memory Audit Protocol. 40/40 doc-consistency tests pass; SDLC.md grew 11 lines (clean, no skill-token-cap impact).
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
After-Session Memory Audit Protocol capture from today's two-release arc (v1.76.0 + v1.77.0, 5 PRs total). Promotes 5 lessons that bit us during the session or would silently bite us again if left uncodified.
What changed
11 lines added to `SDLC.md` ## Lessons Learned section, distributed across 4 categories:
Each entry cites the originating PR or incident date per Memory Audit Protocol.
Why this matters
The `--auto` and monitor-loop bugs ate ~10 turns of wall-clock today. The version-bump checklist gap caused two CI failures (v1.76.0 first attempt and v1.77.0 first attempt). The CC-install dual-binary bug confused the maintainer about whether the upgrade had taken. The negative-claim research bug burned a full PR worth of work (PR #350 corrected PR #348's wrong verdict). All preventable with these notes.
Test plan