Use this skill to create or repair Supersigil spec documents for one bounded feature or prefix. Augment the user's existing brainstorming or planning workflow; do not invent product direction they have not asked for.
Write string literal attributes only. Even if schema examples still show JSX expression syntax like refs={["..."]}, author docs as refs="a, b" and paths="x, y". The parser and lint rules reject expression attributes.
-
Bound the scope to one feature, subsystem, or import batch.
Do not try to normalize the whole repo at once.
-
Inspect the current state before editing.
Run supersigil schema --format json to get the current component and document type definitions.
Run supersigil ls --format json to see what already exists for the feature.
Run supersigil context <id> and supersigil status <id> on the main requirement or design doc when one already exists.
Run supersigil plan <id_or_prefix> to see uncovered criteria and pending tasks.
-
Prefer existing material over blank documents.
If .kiro/specs exists and the user wants Supersigil docs, import first, then refine the generated MDX.
If Supersigil docs already exist, inspect them before rewriting.
If no Supersigil docs exist yet, scaffold with supersigil new.
-
Keep every authored document in status: draft.
Use later statuses only when the document actually earned them.
Do not promote requirement or design docs based only on lint.
Treat draft as the safe working state until verify is clean and the user has reviewed the result.
-
Run the requirements phase first.
Author or refine the requirement doc before design or tasks.
Reuse imported or existing prose when it is already good enough.
Start from supersigil new scaffolds, then expand them with the patterns in references/templates.md when they need richer structure.
-
Pause for a requirement feedback round.
Show the user the drafted requirement criteria.
Ask for feedback before moving on to design.
Refine the requirement-phase docs based on that feedback instead of pushing ahead.
-
Run the design phase second.
Author the design doc only after the requirement feedback round has been incorporated.
Keep the design tied to the reviewed requirement shape.
-
Record design decisions where they belong.
When a feature involves only a few decisions, embed <Decision>,
<Rationale>, and <Alternative> components directly in the design doc.
For large, scoped decisions with non-obvious tradeoffs, rejected
alternatives worth recording, or choices that future contributors will
question, suggest a dedicated ADR (supersigil new adr <feature>/<name>).
Link decisions to requirement criteria with <References refs="...">.
Use standalone="..." on decisions that have no corresponding requirement.
ADR statuses are draft → review → accepted → superseded.
-
Pause for a design feedback round.
Show the user the design direction, boundaries, and major implementation choices.
Include any ADRs authored in this round.
Refine the design doc and ADRs before creating tasks.
-
Run the tasks phase last.
Create dependency-ordered tasks from the current requirement and design graph.
Keep tasks actionable and criterion-linked.
-
Offer a tasks feedback round.
Let the user adjust task granularity, ordering, or scope before handoff to implementation.
Refine the tasks doc if the user wants another pass.
-
Run supersigil verify after every write.
Treat lint cleanliness as the minimum quality bar.
If lint fails, fix that before doing more structural work.
-
Rebuild the graph after structural edits.
Run supersigil ls, supersigil context, supersigil plan, or supersigil graph after adding or changing refs.
If these commands fail after a change, assume you broke cross-document refs or task dependencies and fix that immediately.
-
Run supersigil verify before claiming the feature spec is ready.
Fix uncovered criteria, missing test mappings, stale tracked files, and status inconsistencies that matter for the scoped feature.
If the user is still drafting and wants to defer a finding, keep the relevant doc at status: draft and state the remaining gap clearly.
-
Use supersigil status to decide handoff readiness.
Project the next step from the actual state: more spec work, human review, or implementation.
Use supersigil affected --since <ref> when the user wants to review which docs source changes may have invalidated.
-
End with a concrete handoff.
Summarize which docs are lint-clean, which docs are verify-clean, which review rounds were completed, which IDs or prefixes to inspect with context, plan, and status, and what remains open before execution.
When requirements, design, and tasks have each had their review pass, and the scoped docs are lint-clean and verify-clean enough for honest execution, suggest ss-feature-development if that skill exists. Otherwise hand off by pointing the user to:
