refactor(planning): tighten template for clarity#7
Merged
Conversation
- Reduce from 248 to 121 lines - "Micro Acceptance" → "Test", "Success Criteria" → "Done when" - Show one phase example instead of three redundant ones - Mark optional sections with "(if applicable)" - Remove redundant Usage Notes and What to avoid sections
Keep structural improvements but restore: - TDD relationship explanation before phases - Second phase example showing pattern - "How to Create a Plan" step-by-step - "What to Avoid" section
Following skill-creator guidelines: - Concise, imperative instructions - Examples over explanations - Remove what Claude already knows - Consolidate overlapping content Changes: - Planning: Streamline SKILL.md with clear rules/steps - Planning: Merge planning-approach.md into guidelines.md - Planning: Tighten template.md to just the template - Implementation: Direct workflow in SKILL.md - Implementation: Trim reference files, remove SOLID/DRY theory Total: 1433 → 788 lines (45% reduction) All files under 150 lines
Like discussion skill, set the scene for Claude: - Planning: "expert technical architect" translating decisions into plans - Implementation: "disciplined TDD practitioner" executing with precision
Restored: - "When to Reference Discussion" section to implementation SKILL.md - "Write test names first" guidance to tdd-workflow.md - "Core Principles" section to planning guidelines.md - "Specificity Levels" examples to planning guidelines.md - Explicit "Wait for user confirmation" note to plan-execution.md
Reverts aggressive refactor that removed too much context. Keeps only the persona additions we agreed on: - Implementation: "expert senior developer" with TDD discipline - Planning: "expert technical architect" translating decisions
- Convert Python examples to PHP - Add AAA (Arrange-Act-Assert) comments to test example - Keep existing context/content from restored files
All reference files now contain only rules, principles, and dos/don'ts. Code examples removed since Claude already knows TDD and coding patterns. Skills should direct behavior, not teach concepts. Files trimmed: - code-quality.md: Just SOLID, DRY, YAGNI principles - tdd-workflow.md: Just the cycle and rules - plan-execution.md: Just execution flow - guidelines.md: Just sizing rules and checklists - planning-approach.md: Just workflow steps - template.md: Kept skeleton, removed example tasks
New skill validates implementation against discussion decisions and plan acceptance criteria. Produces structured feedback (approve/request changes) without fixing code. Four-phase workflow: 1. Discussion - WHAT and WHY 2. Planning - HOW 3. Implementation - DOING 4. Review - VALIDATING Updated all existing skills and CLAUDE.md to reference 4-phase workflow.
leeovery
deleted the
claude/create-implementation-skill-01PpRCALqvCDttX6Xn5bsRtP
branch
leeovery
added a commit
that referenced
this pull request
Apr 20, 2026
…oc-only Closes the deferred-issues ledger for the knowledge-base pre-merge cleanup pass. 16 of 18 items fixed in code across earlier commits on this branch; #7 ('--work-unit' as boost not filter) stays open as a deliberate design choice already documented in SKILL.md.
leeovery
added a commit
that referenced
this pull request
Apr 21, 2026
The flag --work-unit meant different things on different commands:
knowledge query --work-unit X → re-rank BOOST (results from other
work units still appear)
knowledge remove --work-unit X → FILTER (only X's chunks are removed)
Same spelling, opposite semantics. Docs explained it, but the flag
name itself pattern-matched --phase / --topic / --work-type — all
hard filters — so users naturally assumed query's --work-unit was a
filter too.
Split:
- query now takes --prefer-work-unit (re-rank boost). The --prefer-
prefix makes boost semantics obvious at the call site and cannot be
confused with a filter.
- remove keeps --work-unit (filter). Consistent with the other filter
flags, which is how remove uses them anyway.
No command has an overloaded flag. Skill files (contextual-query.md,
knowledge-usage.md, SKILL.md) updated to use --prefer-work-unit.
Test updated. Ledger #7 resolved properly this time.
leeovery
added a commit
that referenced
this pull request
Apr 25, 2026
withRetry skips retry for TypeError, ReferenceError, SyntaxError, RangeError, and UserError — the guard added incrementally across deferred-issue #9 (commit f984476), Important #7's UserError introduction, and the RangeError addition. Behaviour was untested: a future refactor reversing the guard would burn 7s of retry budget on permanent failures with no test catching it. Five new cases in test-knowledge-retry.cjs, one per error class. Each throws the specific type, asserts exactly one call and the original class survives. Confirmed all five fail on pre-guard code (seen 'actual: 3, expected: 1' — 3 retries instead of 1). 11/11 retry tests now pass.
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
2 participants
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.
No description provided.