kubit-proposing-change
Use when making non-trivial changes, modifying public APIs, or proposing new framework features. Use when changes affect multiple files or require design decisions.
When & Why to Use This Skill
This Claude skill facilitates the structured process of proposing significant changes to the Kubit framework. It guides developers through creating formal RFCs (Request for Comments) for non-trivial modifications, public API updates, and major architectural decisions, ensuring that all changes are synchronized across types, specifications, and documentation.
Use Cases
- Modifying public API signatures that require synchronized updates across core types, documentation, and usage examples.
- Proposing and designing new major subsystems or features, such as authentication or validation layers, using a standardized RFC template.
- Documenting complex architectural decisions with trade-offs and alternatives to maintain a transparent decision log in SPEC.md.
- Managing non-trivial changes that affect multiple files to ensure consistency between implementation, skeleton examples, and API specifications.
| name | kubit-proposing-change |
|---|---|
| description | Use when making non-trivial changes, modifying public APIs, or proposing new framework features. Use when changes affect multiple files or require design decisions. |
Proposing Changes to Kubit
Overview
Non-trivial changes require synchronized updates across types, spec, skeleton, and docs. Major changes need an RFC.
When to Use
- Modifying public API
- Adding new subsystem or major feature
- Changes affecting multiple files
- Design decisions with trade-offs
RFC Trigger
Create RFC in docs/rfcs/ when:
- Adding new subsystem (Auth, Validation, etc.)
- Changing existing API signatures
- Architectural decisions with alternatives
- User explicitly requests design discussion
Skip RFC for:
- Bug fixes in types
- Adding examples to skeleton
- Documentation clarifications
- Internal refactoring
RFC Template
Create docs/rfcs/YYYY-MM-DD-slug.md:
# RFC: [Title]
## Summary
One paragraph overview.
## Motivation
Why is this needed? What problem does it solve?
## Public API Changes
TypeScript signatures for new/changed APIs.
## Example Usage
How it looks in skeleton/.
## Implementation Notes
Key considerations for future implementation.
## Alternatives Considered
What else was considered and why rejected.
## Test Plan
How to verify this works (mapped to skeleton/tests/).
## Required Updates
- [ ] packages/core/*.d.ts
- [ ] docs/SPEC.md
- [ ] skeleton/*
- [ ] CLAUDE.md (if docs changed)
Synchronized Updates
Any API change requires ALL of these:
| File | Update |
|---|---|
skeleton/* |
Usage example |
packages/core/*.d.ts |
Type definitions |
docs/SPEC.md |
API documentation |
.claude/CLAUDE.md |
If docs/ changed |
Change Process
digraph change_flow {
"Non-trivial change?" [shape=diamond];
"Needs RFC?" [shape=diamond];
"Create RFC" -> "Discuss with user" -> "Update SPEC Decision Log";
"Make synchronized updates" -> "Verify tsc passes" -> "Done";
"Non-trivial change?" -> "Needs RFC?" [label="yes"];
"Needs RFC?" -> "Create RFC" [label="yes"];
"Needs RFC?" -> "Make synchronized updates" [label="no"];
"Update SPEC Decision Log" -> "Make synchronized updates";
}
Decision Log Entry
When decision is made, add to SPEC.md:
### YYYY-MM-DD: [Decision Title]
**Context:** [What prompted this]
**Decision:** [What was decided]
**Rationale:** [Why]
**Alternatives rejected:** [What else was considered]