csk-refine
Skill1 starsChanged 4 months agoMITView on GitHub
Refine an existing feature specification or the master product contract. Use PROJ-X for feature changes and --master for product-goal, USP, journey, interface, contribution-map, or system-gap changes.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- 1-csk-initSkill
- 2-csk-write-specSkill
- 3-csk-architectureSkill
- 4-csk-frontendSkill
- 5-csk-backendSkill
- 6-csk-qaSkill
- 7-csk-deploySkill
- audit-plan-loopSkill
- claude-skill-proxy-syncSkill
- create-worker-worktreeSkill
- csk-adopt-plan-scaffoldSkill
- csk-helpSkill
- csk-startSkill
- finish-branchSkill
- pull-main-ffSkill
- review-loopSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
41 rules. About 0 are common, 27 are distinctive, and 14 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈27
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Before reading or writing project source-of-truth files, resolve adapter config according to .claude/rules/adapter-config.md.
- Distinctive: line 13
Default paths in this skill are fallbacks only:
- Very specific: line 20
If the adapter config provides alternate paths, use those paths exactly and do not also create the defaults.
- Very specific: line 29
If no argument was provided, ask whether the user wants --master or a feature ID, and list existing features.
- Distinctive: line 34
Read the master feature if it exists.
- Very specific: line 35
Read docs/engineering-principles.md if it exists.
- Very specific: line 36
Read .claude/rules/workflow-state.md and .claude/rules/loop-policy.md if they exist.
- Distinctive: line 37
Read the feature index.
- Distinctive: line 38
Read the architecture record when the refinement touches technology, implementation, deployment, operations, or local/cloud boundaries.
- Very specific: line 40
If the PRD is still a template, stop and recommend /1-csk-init with the product idea.
- Distinctive: line 43
Ask one question at a time.
- Distinctive: line 44
Always provide a recommended answer the user can confirm or correct.
- Distinctive: line 45
Follow the conversation instead of a fixed script.
- Distinctive: line 47
Ask only about changed, missing, or contradictory information.
- Distinctive: line 48
Stop when the intended changes and downstream effects are clear.
- Distinctive: line 51
Use this mode for a missing, partial, outdated, or challenged master product contract.
- Very specific: line 53
If the feature index has no roadmap entries, stop and recommend /1-csk-init to complete project initialization first.
- Distinctive: line 56
Read all existing feature specs relevant to product-level outcomes, journeys, interfaces, or gaps.
- Distinctive: line 57
Treat the feature index and implemented behavior as evidence, not automatic authority over the approved product goal.
- Distinctive: line 83
Write system-level acceptance criteria in German:
- Distinctive: line 89
Do not copy feature-level criteria.
- Very specific: line 92
Before saving, apply the planning loop from .claude/rules/loop-policy.md:
- Distinctive: line 100
Create or update the master feature using its existing shape.
- Distinctive: line 101
Update the PRD only if product vision, constraints, metrics, or roadmap changed.
- Distinctive: line 102
Update the feature index only if names, dependencies, priorities, or statuses clearly changed.
- Very specific: line 103
Do not create an individual feature spec.
- Very specific: line 104
Do not change architecture decisions directly.
- Distinctive: line 107
Read the complete matching feature spec.
- Distinctive: line 114
Use the answer to choose a path.
- Distinctive: line 117
Run a targeted interview:
- Distinctive: line 119
Do edge cases, dependencies, or scope boundaries change?
- Very specific: line 139
If splitting is approved, create the new spec through the /2-csk-write-spec workflow and update the feature index.
- Very specific: line 141
If technology is reopened, update product requirements but do not change implementation directly.
- Distinctive: line 147
Update and re-read the feature spec.
- Distinctive: line 150
Add decisions with rationale and date.
- Distinctive: line 151
Add unresolved questions as open items.
- Distinctive: line 152
Update the feature index if status or dependencies changed.
- Distinctive: line 153
Update the PRD if the roadmap changed.
- Distinctive: line 154
Update the master feature if product-level truth changed.
- Very specific: line 180
Before ending, preserve only durable unfinished or blocked work through /csk-start (show proposed rows as PENDING-AUTH and ask once).
- Very specific: line 184
Before choosing the handoff, read the transition and routing SSOT in .claude/rules/workflow-state.md.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Product And Feature Refiner
Adapter Config And Paths
Before reading or writing project source-of-truth files, resolve adapter config according to .claude/rules/adapter-config.md.
Default paths in this skill are fallbacks only:
docs/PRD.mddocs/master-feature.mddocs/architecture.mdfeatures/INDEX.mdfeatures/PROJ-X-feature-name.md
If the adapter config provides alternate paths, use those paths exactly and do not also create the defaults. If adrRequired is true, remind the user to follow the repository ADR process before changing source-of-truth documentation or configuration.
Role
Act as an experienced Product Manager and System QA thinker. Improve existing product truth without discarding history or bypassing architecture ownership.
Choose A Mode
--master: create, backfill, or refine the whole-product contract after a PRD exists.PROJ-X: improve, extend, split, or challenge one feature specification.
If no argument was provided, ask whether the user wants --master or a feature ID, and list existing features. Do not guess the mode.
Common Preparation
- Resolve adapter config and paths.
- Read the PRD.
- Read the master feature if it exists.
- Read
docs/engineering-principles.mdif it exists. - Read
.claude/rules/workflow-state.mdand.claude/rules/loop-policy.mdif they exist. - Read the feature index.
- Read the architecture record when the refinement touches technology, implementation, deployment, operations, or local/cloud boundaries.
If the PRD is still a template, stop and recommend /1-csk-init with the product idea.
Interview Principle
- Ask one question at a time.
- Always provide a recommended answer the user can confirm or correct.
- Follow the conversation instead of a fixed script.
- Explore source-of-truth files and code before asking what they can answer.
- Ask only about changed, missing, or contradictory information.
- Stop when the intended changes and downstream effects are clear.
Master Mode: --master
Use this mode for a missing, partial, outdated, or challenged master product contract. Do not require a feature ID.
If the feature index has no roadmap entries, stop and recommend /1-csk-init to complete project initialization first. The Feature Contribution Map cannot be backfilled without a roadmap.
Read Additional Context
- Read all existing feature specs relevant to product-level outcomes, journeys, interfaces, or gaps.
- Treat the feature index and implemented behavior as evidence, not automatic authority over the approved product goal.
Opening Question
Always ask first:
"What changed or remains unclear at the whole-product level?" My recommendation: Start with the product promise, critical journey, or system-level gap that no individual feature spec can resolve alone.
Determine whether this is:
backfill: the master feature is missing or still a template.targeted: one product-level outcome, journey, interface, quality attribute, or gap changed.fundamental: the product goal, USP, roadmap logic, or operating model must be challenged.
Reuse existing PRD and feature answers. Cover only affected or missing areas:
- Product Goal and Unique Value Proposition.
- Target Outcomes and success evidence.
- Master Acceptance Criteria.
- Critical User Journeys and System Capabilities.
- Interfaces And Boundaries.
- Quality Attributes.
- Frontier AI / Pipeline Needs.
- Local / Cloud / Hybrid Expectations.
- Feature Contribution Map.
- Missing Or Could-Be-Better.
- Decision Log.
Write system-level acceptance criteria in German:
- [ ] Angenommen [System-/Nutzerkontext], wenn [End-to-end-Aktion], dann [messbares Gesamtziel]Do not copy feature-level criteria. Map features to outcomes and journeys, including dependencies, system risk if missing, and whether each is MVP, differentiator, or enhancement. Flag roadmap items that no longer contribute.
Master Planning Hardening
Before saving, apply the planning loop from .claude/rules/loop-policy.md:
- Audit the proposed master changes against the PRD, feature map, engineering principles, known architecture constraints, and existing evidence.
- Plan corrections and downstream updates.
- Refine the master feature and only the related product/roadmap records.
- Log unresolved gaps and route architecture, feature-spec, or QA follow-ups.
Present the master changes for user approval. Then:
- Create or update the master feature using its existing shape.
- Update the PRD only if product vision, constraints, metrics, or roadmap changed.
- Update the feature index only if names, dependencies, priorities, or statuses clearly changed.
- Do not create an individual feature spec; use
/2-csk-write-spec PROJ-X. - Do not change architecture decisions directly; route them to
/3-csk-architectureor the configuredarchitectureAuthority.
Feature Mode: PROJ-X
Read the complete matching feature spec. If the ID does not exist, stop and list existing features.
Opening Question
Always ask first:
"What brought you back to this spec?"
Use the answer to choose a path.
Path 1: Something Changed
Run a targeted interview:
- What changed and which user stories or criteria are affected?
- Do edge cases, dependencies, or scope boundaries change?
- Does this affect the master goal, USP, journeys, interfaces, contribution map, or system gaps?
- Does this affect locality, AI/pipeline, performance, security, or evidence expectations?
Path 2: Implementation Revealed Gaps
Determine:
- Which scenario was missing.
- Whether it becomes a criterion, edge case, or separate feature.
- Which existing criteria change.
- Whether this reveals a system-level gap for the master feature.
- Which planning or review-loop gate now applies.
Path 3: Fundamental Challenge
Challenge:
- Which assumption is wrong.
- Whether the user story remains correct.
- Whether the feature should split, merge, shrink, or be cancelled.
- Whether it still strengthens the master goal and USP.
- What moves out of scope.
If splitting is approved, create the new spec through the /2-csk-write-spec workflow and update the feature index.
If technology is reopened, update product requirements but do not change implementation directly. Route the decision to /3-csk-architecture or the configured architectureAuthority.
Update The Feature Spec
For complex, high-risk, AI/pipeline, local/cloud, security/privacy, performance-sensitive, or architecture-affecting changes, apply the planning hardening loop before finalizing.
After approval:
- Update and re-read the feature spec.
- Append new external briefing references to
Briefing Provenance; never replace earlier references. - Close resolved Open Questions with a resolution note and date.
- Add decisions with rationale and date.
- Add unresolved questions as open items.
- Update the feature index if status or dependencies changed.
- Update the PRD if the roadmap changed.
- Update the master feature if product-level truth changed.
Checklist Before Completion
All Modes
- Mode selected explicitly.
- Existing source-of-truth files read before editing.
- One-question interview used and existing answers reused.
- User reviewed the proposed changes.
- Changed files re-read after saving.
- Planning/review-loop decision recorded where required.
Master Mode
- Product-level change or backfill reason identified.
- Goal, USP, outcomes, criteria, journeys, capabilities, interfaces, quality, locality, contribution, and gaps are complete or explicitly marked open/not applicable.
- Planning hardening loop completed.
- PRD and feature index reconciled only where needed.
- Architecture changes routed to the correct owner.
Feature Mode
- Feature path selected and all affected criteria, edge cases, dependencies, and scope resolved.
- Decision Log and Open Questions maintained.
- Briefing provenance preserved and appended when applicable.
- Product-level changes reflected in the master feature.
Handoff
Before ending, preserve only durable unfinished or blocked work through
/csk-start (show proposed rows as PENDING-AUTH and ask once); do not create
same-turn task churn.
Before choosing the handoff, read the transition and routing SSOT in
.claude/rules/workflow-state.md.
For --master, choose exactly one next command from the current feature status. Include the real feature ID or adapter-resolved spec path. Do not present a menu of possible next steps.
For PROJ-X, also choose exactly one next command from the current feature status. A split or reopened technology decision normally routes to /3-csk-architecture features/PROJ-X-name.md; substitute the real adapter-resolved path.
Git Commit
docs: Refine product or feature specificationDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

