skills.rest
jcafeitosa
jcafeitosaCOMMUNITY
Explore all skills by this author →
Website𝕏@jcafeitosaGitHub

write-a-spec

Writes implementation specs under specs/ from accepted proposals with decision logs and test plans.

Updated Sep 7, 2026
Search Tags:#implementation planning#technical design#spec#migration plan#decision log#proposal#openknowledge
One-click install
npx skills add https://github.com/jcafeitosa/anxionOS --skill write-a-spec-jcafeitosa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-a-spec
Source: https://github.com/jcafeitosa/anxionOS/tree/main/.cursor/skills/write-a-spec
Command: npx skills add https://github.com/jcafeitosa/anxionOS --skill write-a-spec-jcafeitosa

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Turning an accepted proposal into a buildable implementation spec often fails because the author designs against an imagined system, silently resolves open questions, or loses the reasoning behind irreversible choices. This Skill enforces a gated workflow that maps the current system first, records one-way-door decisions, and keeps open questions visible. ## Core Features & Use Cases - Mandatory execution order: Hard gates require finding the parent proposal, mapping the current system with real code pointers, and confirming scope before any spec file is created. - Decision Log and Open Questions: Appends a Decision Log for one-way-door choices (with reversal conditions) and a live Open Questions backlog with closing evidence and deciders. - Migration and test planning: Produces real migration states, tiered test plans, and optional plan.md/tasks.md when the spec is greenlit for build. - Use Case: After a payment-retries proposal is accepted, use this Skill to create specs/004-payment-retries/spec.md with goals, non-goals, design options, a decision log, and a rollout plan linked back to the proposal. ## Quick Start Ask the agent to write a spec for the accepted payment retries proposal and scope the implementation end to end.

Frequently Asked Questions about write-a-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an implementation spec from an accepted proposal?▼

Run this Skill after a proposal reaches accepted status. It finds the parent proposal, maps the current system from real code, confirms scope at a stop gate, then creates specs/NNN-name/spec.md from the spec template with goals, design, decision log, and test plan.

What is a decision log in a software spec?▼

A decision log records one-way-door choices made during spec writing, each with options considered, the choice, rationale, date, and a reversal condition. It is scoped to the spec itself and is separate from project-wide ADRs in decisions/.

Can I write a spec without an accepted proposal?▼

The Skill treats a missing or unaccepted proposal as a hard gate. It stops and asks whether to frame a proposal first or proceed with explicit acknowledgement, recording that choice in the decision log rather than skipping silently.

Does this Skill work without the OpenKnowledge MCP server?▼

No. The frontmatter states compatibility requires an agent host with the OpenKnowledge MCP server configured, since the workflow uses OpenKnowledge verbs like write, edit, search, audit, and links on the knowledge base.

When should plan.md and tasks.md be created for a spec?▼

Only when the spec is actually greenlit for implementation. Creating them while the spec is still a draft produces stale scaffolding; the Skill defers them until build approval and links them via parent_spec frontmatter.

Related Skills

Explore More Software Engineering Skills→
inkeepinkeep
3.9k

write-a-spec

Writes implementation specs under specs/ from accepted proposals with decision logs and test plans.

Official
Advanced
bernieweb3bernieweb3

hackathon-task-planner

Decompose MVP features into time-boxed tasks with roles and critical path.

Community
Intermediate
amoutiersamoutiers
1

x-adr

Draft architectural decision records using adr-template.md and update the ADR index.

Community
Advanced
IPADS-SAIIPADS-SAI
44

doc-coauthoring

Guide collaborative drafting of specs, RFCs, and decision docs.

Official
Advanced