rewrite-specs

What problem does it solve?

After a design direction is approved via brainstorming, existing design docs, specs, and substrate artifacts often remain in future tense, contain obsolete claims, or contradict the new direction, leading to confusion during implementation and review and making it hard to track what actually changed.

Core Features & Use Cases

• Hard rewrite of substrate artifacts: Rewrites all relevant design docs, specs, behavior matrices, named invariants, and gotchas to use present-tense end-state language, removing obsolete claims entirely instead of annotating them as deprecated.
• Structured commit with classification: Classifies the rewrite as Pure implementation, Design, or Mixed, and commits all changes atomically to a dedicated design/<slug> branch with a mandatory classification trailer for downstream validation.
• Isolated worktree operation: Runs all rewrites in an isolated git worktree to ensure changes can be reviewed as a coherent diff and discarded if needed without affecting the main codebase. Use case: For example, after your team approves a new architecture for the user authentication system, use this Skill to rewrite all related specs and docs to describe the new end state as if it is already implemented, giving the implementation team a single source of truth.

Quick Start

Use the rewrite-specs skill to hard-rewrite all design docs and specs for the approved new user authentication architecture to present-tense end-state language, and commit the changes to a dedicated design branch for fresh-eyes review.