Split TIL/spec boundary, add /update-spec skill, sharpen skill design#12
Merged
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Review complete — no issues found. This is a documentation refactor (moving API decisions from The new skill file follows good patterns: imperative instructions, confirm-before-write, explicit "nothing qualifies" guard. ✅ Ready to merge. Cost: $0.18 |
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.
Decisions worth noting
API contract decisions moved from
docs/til.mdtodocs/spec.md. TIL is for reusable patterns (FastAPI, SQLModel, async); spec is for homik-specific decisions (endpoint shape, merge vs reject, cascade behaviour). Mixed together, neither document serves its purpose well./update-specskill created as a companion to/til. Running/tilafter a session now flags homik-specific decisions for/update-specrather than absorbing them into the wrong document.Skill files rewritten as imperative instructions, not documents. Headers and "when to use" sections are for human readers — at runtime, document structure makes Claude process scaffolding before reaching the actual instructions. Imperative voice ("do X", "skip if Y") is more directly actionable.
Sharpness rules added to both skills. "Skip if already covered" is more effective than "be concise" — naming the specific failure mode (padding, restating) outperforms stating a virtue. Each skill now names exactly how it can go wrong and blocks those paths.
confirm-before-writeinstruction added to file-writing skills. Without it, Claude writes first and the user reviews a diff after the fact. Draft → show → confirm → write keeps the user in control at the right moment.skill-template.mdadded to.claude/prompts/. Used when asking Claude to create or revise a skill. Lives inprompts/rather than CLAUDE.md because it's occasional — CLAUDE.md loads every session, so anything in it should be needed most sessions.What's next
Integration tests PR.