Retro improvements: learnings, skills, and guidelines updates

[ahoym]

Summary

• Batch of learnings, guideline refinements, and skill improvements captured across recent session retros
• Staging directory pattern for extract-request-learnings to work around background agent write restrictions
• Curate skill enhancements: decomposition format for large files, refined deletion criteria
• New guidelines for sub-skill invocation, freeform input confirmation, and confidence-level gating
• Surgical conflict reading and template re-read patterns for skill reliability

Changes

Key changes:

• extract-request-learnings — General/private writers now use docs/learnings/_staging/ instead of writing directly to ~/.claude/; orchestrator copies to final locations in foreground (SKILL.md, writer-prompt.md)
• curate skill — Added decomposition report format for 20+ pattern files, confirmation checkpoint for large operations, source-vs-echo and reusability deletion tests (SKILL.md, classification-model.md)
• resolve-conflicts — Surgical conflict reading: grep for markers instead of full file reads, use offset+limit to read only conflict regions (SKILL.md)
• create-pr / create-request — Skill refinements and platform-detection updates (SKILL.md)
• address-request-comments — Added learnings lookup step before addressing comments (SKILL.md)
• guidelines — Freeform input confirmation, behavioral-rules-in-guidelines rule (communication.md), don't ask permission for sub-skill invocations (skill-invocation.md)
• CLAUDE.md — Refined path resolution table for clarity, added Read tool and sync-source sections
• learnings — New patterns across git workflows, multi-agent, skill design, python, process conventions, claude-md authoring, guideline authoring, claude-code, and testing domains (14 files)
• skill-references — Updated GitHub/GitLab command references with expanded coverage
• settings.json — Permission pattern updates
• .gh-replies/ — Migrated reply files to dedicated directory, added to .gitignore

Screenshots

N/A

Test plan

• Verify extract-request-learnings staging flow works end-to-end
• Run curate on a 20+ pattern file to validate decomposition format
• Confirm sub-skill invocations proceed without unnecessary prompts
• Test resolve-conflicts surgical reading on a file with conflict markers

Checklist

• README or docs updated (if needed)

---

Generated with Claude Code

[ahoym]

Suggestions awaiting approval

#	File	Suggestion	Recommendation
1	.claude/settings.json:51	Generalize permission to ~/**/.gh-replies/**	Agree -- broader coverage without security downside
2	.gitignore:6 + 3 other files	Rename .gh-replies/ to change-request-replies/	Agree -- platform-agnostic, manageable blast radius (settings.json, .gitignore, github-commands.md, gitlab-commands.md)

Reply with which to implement (e.g., "all", "1", "1,2") or discuss further.

---

Co-authored with Claude Opus 4.6

[ahoym]

Config Review: PR #24

Reviewed through the claude-config-reviewer lens. Structural changes (curate decomposition, staging pattern, body-file pattern, rebase support) are well-designed. Main concerns are content duplication across learnings spokes and a copy-paste bug.

---

Single Source of Truth Violations

1. claude-authoring-guidelines.md duplicates hub + learnings spoke content

Several sections added to the guidelines spoke are verbatim copies from other files:

Section added	Already exists in
"Avoid Nesting Subdirectories Inside learnings/"	claude-authoring-learnings.md
"Content Type Taxonomy" (full table)	claude-authoring-content-types.md (the hub)
"Genericize Project-Specific Content"	claude-authoring-learnings.md
"Persona-Learning Boundary Test"	claude-authoring-learnings.md

Per hub-and-spoke design, each spoke stays in its lane. These should be removed from the guidelines spoke, keeping only content unique to guideline authoring.

2. "Scope Classification Needs Language-Awareness" appears in both claude-authoring-skills.md AND claude-authoring-learnings.md

Same content, two homes. Since it's about learnings classification (what extraction subagents do), the learnings spoke seems more natural.

3. "Behavioral rules belong in guidelines, not memory" is duplicated

This rule already exists in CLAUDE.md's MEMORY section (always-on context). The copy in communication.md under "Autonomy during execution" is both redundant and oddly placed (it's about content management, not communication).

---

Copy-Paste Bug

4. Wrong takeaway on "Memory Minimalism" in claude-authoring-skills.md

The Memory Minimalism section ends with:

- **Takeaway**: Multi-session skill flows should include `git fetch` as an early step to prevent stale-branch issues.

This is the takeaway from the previous section ("Multi-Session Skills Need Git Remote Sync"), not Memory Minimalism.

---

Taxonomy Questions

5. Aggressive deletions from claude-authoring-skills.md — verify coverage

~113 lines deleted. Some clearly moved (naming conventions -> cross-repo-sync.md). But several practical sections don't have an obvious new home:

• "User Interaction Points" (mark steps needing user input)
• "Bash Commands in Skills" (--force-with-lease, full commands, HEREDOC)
• "File Operations" (temp files in ./tmp/)
• "Validating Skill Changes" (structure/content/permissions/function checklist)
• "When NOT to Add Routing Hints" (nuance to the trigger phrases section)

Are these source-vs-echo deletions (covered elsewhere) or clutter-based? "When NOT to Add Routing Hints" in particular adds value the trigger phrases section alone doesn't provide.

6. code-quality-instincts.md — some additions are basic OOP

"Eliminate duplicate entities through inheritance," "Raise exceptions instead of returning None," "Name the primary method run()" — per the "LLM Knows X != LLM Consistently Applies X" test, do these actually fail to be applied unprompted? If yes, they earn their keep. If not, they add context cost for patterns the model already handles.

Also: missing newline at end of file.

---

Good Patterns

• Curate skill decomposition into content-mode.md / skill-mode.md — clean application of Skill Decomposition by Execution Path. Decomposition report format for 20+ pattern files is a nice addition.
• Staging directory pattern — elegant workaround for background agent write restrictions. Well-documented in both skill and multi-agent-patterns.md.
• --body-file pattern — solves HEREDOC permission prompts. Branch name in temp filename for parallel safety.
• resolve-conflicts rebase support — thorough: stash handling, ours/theirs inversion, per-commit resolution, force-with-lease.
• GitHub/GitLab quoting — "..." -> '...' for API URLs prevents shell expansion.
• Pagination fix — direction=desc + per_page=100 prevents newest comments from hiding.
• change-request-replies/ rename — platform-agnostic, good.

---

Minor

• Staging cleanup resilience: Step 9's rm -rf docs/learnings/_staging/ after copy — if copy partially fails, rerunning has nothing to copy. Consider keeping staging until next run.
• GitLab glab mr comment still uses "$(cat ...)" subshell (no --body-file equivalent). May still trigger permission prompts for complex bodies.

[ahoym]

Config Review: PR #24

Reviewed through the claude-config-reviewer lens. Structural changes (curate decomposition, staging pattern, body-file pattern, rebase support) are well-designed. Main concerns are content duplication across learnings spokes and a copy-paste bug.

Good Patterns

• Curate skill decomposition into content-mode.md / skill-mode.md — clean application of Skill Decomposition by Execution Path. Decomposition report format for 20+ pattern files is a nice addition.
• Staging directory pattern — elegant workaround for background agent write restrictions. Well-documented in both skill and multi-agent-patterns.md.
• --body-file pattern — solves HEREDOC permission prompts. Branch name in temp filename for parallel safety.
• resolve-conflicts rebase support — thorough: stash handling, ours/theirs inversion, per-commit resolution, force-with-lease.
• GitHub/GitLab quoting — "..." -> '...' for API URLs prevents shell expansion.
• Pagination fix — direction=desc + per_page=100 prevents newest comments from hiding.
• change-request-replies/ rename — platform-agnostic, good.

---

Review generated with Claude Code using the claude-config-reviewer persona.

[ahoym]

Suggestions awaiting approval

#	File	Suggestion	Recommendation
7	extract-request-learnings/SKILL.md:100	Remove rm -rf staging cleanup, let next run's mkdir -p handle it	Agree -- simple, staging dir is gitignored
8	gitlab-commands.md:61	Add comment noting glab lacks --body-file, $(cat ...) may trigger prompts	Agree -- documents a known limitation

Auto-fixing (typo/bug fixes):

• Add resumable execution state learning #1: Remove duplicated spoke sections from claude-authoring-guidelines.md
• Rename skill-reference to skill-references #2: Remove duplicated "behavioral rules" paragraph from communication.md
• Prune redundant learnings migrated to personas/skills #3: Fix copy-paste takeaway in claude-authoring-skills.md:388
• Add context window optimization as explicit curation objective #4: Remove duplicated scope classification section from claude-authoring-skills.md

Clarification requests (awaiting your input):

• Add persona tiering and compression target learnings #5: Were deleted sections (When NOT to Add Routing Hints, etc.) intentionally cut or accidentally lost?
• Clarify ambiguous pronouns in communication guidelines #6: Do the OOP patterns in code-quality-instincts.md have session evidence? (Will fix missing newline either way)

Reply with which suggestions to implement (e.g., "all", "7,8") or answer the clarification questions.

---

Co-authored with Claude Opus 4.6

[ahoym]

Claude Config Reviewer: Retro improvements

Second review pass after duplications and copy-paste bug were addressed. The structural changes are solid — curate decomposition, staging pattern, body-file pattern, and rebase support are all well-designed. Remaining items are minor.

Findings

• Deleted "When NOT to Add Routing Hints" from claude-authoring-skills.md — this nuance (knowing when not to add routing hints) isn't covered elsewhere and complements the "Discoverability via Trigger Phrases" section. Worth reconsidering.
• Several deleted sections from claude-authoring-skills.md (~113 lines) don't have obvious new homes: "User Interaction Points", "Bash Commands in Skills" (--force-with-lease), "File Operations" (temp files), "Validating Skill Changes". If these were source-vs-echo deletions, great — but a quick coverage check is worthwhile.
• Basic OOP patterns in code-quality-instincts.md (inheritance for shared fields, raise vs return None, run() naming) — per "LLM Knows X ≠ LLM Consistently Applies X" test, were these actually missed in sessions?
• Missing newline at end of file in code-quality-instincts.md
• Staging cleanup resilience — rm -rf after copy means a partial copy failure leaves nothing to retry from
• GitLab glab mr comment still uses $(cat ...) subshell — no --body-file equivalent exists

Positive Signals

• Previous review findings addressed — duplicated sections removed, copy-paste takeaway fixed, "behavioral rules" guideline removed from communication.md
• Curate skill decomposition into content-mode.md / skill-mode.md — clean execution path split with broad sweep correctly kept in content-mode
• Staging directory pattern — elegant workaround, well-documented in both skill and multi-agent-patterns.md
• --body-file pattern across create-pr, create-request, and github-commands — solves HEREDOC permission prompts consistently
• resolve-conflicts rebase support — thorough: stash handling, ours/theirs inversion, per-commit resolution, force-with-lease
• Pagination fix — direction=desc + per_page=100 prevents newest comments from hiding
• #N auto-link gotcha in reply templates — practical catch
• Language tag in extractor prompt for better routing — addresses scope classification issue

---

Generated with Claude Code (Claude Opus 4.6) using the claude-config-reviewer persona.

[ahoym]

Suggestions awaiting approval (updated)

#	File	Suggestion	Recommendation
6	code-quality-instincts.md:103	Remove 3 generic OOP sections + fix missing newline	Agree -- no session evidence they were missed
7	extract-request-learnings/SKILL.md:100	Remove rm -rf staging cleanup line	Agree -- mkdir -p on next run handles it
8	gitlab-commands.md:72	Add comment noting glab lacks --body-file	Agree -- documents limitation

Still pending clarification:

• Add persona tiering and compression target learnings #5: Were deleted sections (When NOT to Add Routing Hints, etc.) intentionally cut or accidentally lost?

Reply with which to implement (e.g., "all", "6,7,8") or answer the clarification.

---

Co-authored with Claude Opus 4.6

[ahoym]

Claude Config Reviewer Re-review: Retro improvements

4 new commits since last review — code-review-request skill, address-request-comments updates, --paginate fix, and reaction -f fix.

Previous Findings

• ✅ 2 resolved (informational comments acknowledged)
• 🔄 3 partially addressed (author agreed but changes not yet committed)
• ❌ 1 not addressed (routing hints deletion — no response)

New Findings

• --paginate is a better fix than the original per_page=100 + direction=desc approach — it supersedes the pagination concern from the first review entirely. The CLI handles page traversal without query params that need quoting. Well-chosen solution.
• New skill and reference additions are well-structured — the code-review-request skill, review API sections in both platform command files, and the React to Comment templates follow existing conventions cleanly.

Positive Signals

• The -f vs -F fix for emoji reactions catches a subtle API type-inference issue before it could bite in production
• Review count tracking for incremental detection is the right approach since the reviews endpoint doesn't support since filtering
• --paginate eliminates an entire class of silent data-loss bugs (comments beyond page 1)

---

Generated with Claude Code (Claude Opus 4.6) using the claude-config-reviewer persona.

[ahoym]

Claude Config Reviewer Review: Retro improvements

This PR has been reviewed across multiple passes in this session. All previously raised concerns (content duplication across spokes, copy-paste takeaway bug, staging cleanup resilience, GitLab limitation documentation) have been addressed. The OOP patterns in code-quality-instincts were questioned, author provided context that they were scraped from actual implementation sessions, and deliberately restored them.

Findings

• No outstanding concerns — all previous findings resolved across 3 review rounds
• The PR is large (30 files, 26 commits) but changes are well-organized by domain: skills, learnings, guidelines, and platform references

Positive Signals

• Curate skill decomposition into mode-specific reference files follows the execution-path-split pattern cleanly
• Staging directory pattern for background agent write restrictions is well-documented across skill and learnings
• --body-file and --paginate patterns consistently applied across platform command references
• Rebase support in resolve-conflicts is thorough with ours/theirs inversion gotcha well-documented
• Language tag addition to extractor prompt addresses the scope classification issue at the source
• Structured footnote convention enables clean multi-agent PR workflows

---

Co-Authored with Claude Code (Claude Opus 4.6)
Persona: claude-config-reviewer
Role: Reviewer