Create technical planning skill for implementation#1
Merged
Conversation
Created comprehensive technical planning skill that transforms discussion documents into actionable implementation plans. This is the second phase of the document-plan-implement workflow. Key features: - Structured implementation phases with clear tasks - Code examples (pseudocode and actual code) for complex patterns - Comprehensive testing strategies - Edge case handling from discussion documents - Rollback and monitoring plans - Complete templates and guidelines Includes: - SKILL.md: Main skill definition with workflow - template.md: Implementation plan template - guidelines.md: Best practices for creating plans - planning-approach.md: Detailed approach and methodology - Packaged .skill file for distribution
Added __pycache__ and other Python-generated files to .gitignore to prevent committing build artifacts from skill packaging scripts.
Skills should be kept as source markdown files only. Removed packaged .skill files and added dist/ to .gitignore.
…mplement Added prominent warnings that planning phase creates plan documents but does NOT execute implementation. Implementation is a separate phase.
Reduced SKILL.md from 225 to 93 lines following skill-creator guidelines: - Removed verbose explanations (Claude already knows) - Eliminated duplicate content (details in reference files) - Brief overview with links to detailed reference files - Similar concise structure to discussion-documentation skill - Maintains critical boundaries about not implementing Detailed content remains in: - planning-approach.md (workflow and methodology) - guidelines.md (best practices and examples) - template.md (plan structure)
Renamed discussion-documentation → technical-discussion for consistency. Both skills now clearly show three-phase workflow at top: 1. Discussion (technical-discussion): WHAT/WHY 2. Planning (technical-planning): HOW 3. Implementation (next phase): DOING Each skill shows which phase it handles and what NOT to do. Both are more concise and reference each other.
leeovery
deleted the
claude/create-planning-skill-01NVgEPMHo1EapRD9GsVVG2s
branch
leeovery
added a commit
that referenced
this pull request
Apr 11, 2026
Addresses two gaps between the chunker implementation and the design contract, surfaced during PR #244 review. Issue #1 — merge-up broke content preservation (design line 74) ================================================================ The old merge-up path joined sections with a hard-coded `\n\n`: prev.content = prev.content + '\n\n' + section.text; That separator is injected by the chunker, not drawn from the source. If the gap between the parent and the merge-up section contained anything other than exactly two newlines (e.g. a blank line with trailing whitespace, or a comment), the merged chunk was no longer a verbatim substring of the source — silently violating the global "no lossy compression" invariant. Fix: track source line ranges on every section during buildSections and maintain them through the processing pipeline. merge-up now extends the preceding segment's endLine; chunk content is generated by slicing from the original line array once at the end. Contiguous source slice → verbatim guaranteed, regardless of what sits between the merged sections in the source. Issue #3 — sub-level special_sections was not implemented ========================================================== Task 2-1 states: "own-chunk: always split into its own chunk regardless of heading level". The previous implementation only matched at the split level (H2 for discussion), so an H3 "### Discussion Map" nested inside a regular H2 would remain part of its parent chunk instead of being extracted. Fix: added expandSubLevelSpecials, which walks each split-level section's line range and carves out any sub-level heading whose text matches a special_sections entry. Precedence rule: if the parent section's heading is itself in special_sections, the parent's action wins and no sub-carving happens — "Discussion Map as H2" stays one chunk. Sub-level matching handles own-chunk and skip; merge-up is a split-level concept only and sub-level merge-up entries are treated as regular sub-headings. Issue #2 — own-chunk + size fallback ambiguity ============================================== The task wording "always split into its own chunk" is ambiguous: does own-chunk bypass the max_lines fallback split, or not? The previous code made a silent choice. Added an inline comment documenting the decision and its reasoning: own-chunk is interpreted as literal one chunk, so a large Discussion Map stays intact even if it exceeds max_lines. special_sections mark semantic units the user has declared atomic, and splitting them would defeat that declaration. Testing ======= - Two new merge-up tests assert the verbatim invariant on synthetic sources with non-`\n\n` separators — would have caught the original bug. Both pass. - One new sub-level extraction test using a synthetic fixture (`sub-level-special-fixture.md`) where `### Discussion Map` lives inside `## Plan`. Verifies the Map is extracted, the parent's intro stays, and "## Context"/"## Summary" boundaries are unaffected. - One parent-wins precedence test against the real pigeon discussion fixture — makes the precedence rule explicit. Additional real fixtures for structural diversity ================================================== - spec-deep-nested-fixture.md (tick v1 tick-core/specification.md, 810L) — one huge H2 ("## Specification") that gets fallback-split into 11 H3 chunks, plus one standalone H2 ("## Dependencies"). Proves the flat fallback chain handles real artifacts with a single dominant H2. - research-oversized-h3-fixture.md (tick v1 research/exploration.md, 567L) — contains a ~310-line H3 "Session 1" that stays intact (no recursion, reported by knowledge status in Phase 4). - discussion-q-style-fixture.md (tick v1 cli-command-structure-ux.md, 416L) — Q1..Q6 discussion shape with no Discussion Map, proves the chunker copes with non-canonical discussion variants. - spec-folio-fixture.md (folio template-authoring-system/specification.md, 617L) — different spec structure from portal/tick for diversity. Regression: 119/119 tests green. Bundle 132.9 KB (up 1.3 KB, 17 KB under the 150 KB ceiling). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
leeovery
added a commit
that referenced
this pull request
Apr 20, 2026
…OCTOU) indexSingleFile computes embeddings with effectiveProvider.dimensions() BEFORE acquiring the store lock. If a concurrent rebuild rewrote the store schema with different dimensions between embed and insert, insertDocument would fail (wrong vector width) or corrupt the index. Rare in single-developer use, but Phase 5+ skill orchestration can run multiple index/rebuild flows back to back. Inside the lock, after reloading the store, compare the reloaded metadata's dimensions to what we embedded with. On mismatch, throw — the withRetry wrapper at the CLI entry re-runs from the top with fresh metadata and a fresh embedBatch against the new schema. Closes deferred-issues #1.
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.
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.