shape-revision

Create or update spec revisions when requirements move between source and destination specs.

26|3|Updated Oct 9, 2025
One-click install
npx skills add https://github.com/davidlee/spec-driver --skill shape-revision
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: shape-revision
Source: https://github.com/davidlee/spec-driver/tree/main/.spec-driver/skills/shape-revision
Command: npx skills add https://github.com/davidlee/spec-driver --skill shape-revision

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Shape the right spec revision when requirements or responsibilities move, so authority and lineage don’t silently drift away from the audit trail.

Core Features & Use Cases

  • Revision-first reconciliation: Establishes spec-change intent before delta scoping when policy or doctrine requires revision-first flow.
  • Doctrinal path selection: Applies doctrine checkpoints to decide whether to patch an existing spec, create/update a revision, or escalate to consultation.
  • Topology-safe authorship: Prevents overlapping or competing truths by closing the current authority branch before creating new artifacts.
  • Structured, section-scoped output: Authors revisions with explicit scope, owning context, source/destination specs, requirement movement, and downstream update notes.
  • Audit-aware edge handling: Treats evidence as a trigger for explicit reconciliation and supports post-audit correction workflows.

Quick Start

Tell your agent to run shape-revision with the change request, source/destination spec IDs, and the requirement IDs that moved, then have it produce a revision rationale or a direct patch decision using the doctrine pass.

Frequently Asked Questions about shape-revision

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

FAQPage Schema
How do I reconcile spec authority when requirements move between specs?

Spec authority reconciliation uses revision-first workflows to establish spec-change intent before delta scoping. It applies doctrine checkpoints to decide whether to patch an existing spec, create a revision, or escalate to consultation when audit reconciliation indicates authority must move.

When do I need a spec revision instead of a direct patch?

A spec revision is needed when policy or doctrine mandates revision-first flow, or when audit reconciliation indicates authority must move. Doctrinal path selection evaluates artifact placement to decide between patching, revising, or escalating to consultation.

How do I document requirement movement for audit reconciliation?

Document requirement movement by authoring structured, section-scoped revisions that include explicit scope, owning context, source and destination spec IDs, and downstream update notes. This topology-safe authorship prevents overlapping truths and maintains a correct audit trail.

What is topology-safe authorship for spec revisions?

Topology-safe authorship prevents overlapping or competing truths by closing the current authority branch before creating new artifacts. This practice ensures spec authority and lineage do not silently drift away from the audit trail during requirement shifts.

Does shape-revision work without external dependencies?

Yes, shape-revision operates without external dependencies. It uses internal doctrine checks to select between patch, revision, or consult paths, processing change requests alongside source and destination spec IDs and moved requirement IDs to produce revision rationales.

What are the limitations of revision-first spec workflows?

A limitation of revision-first workflows is the strict requirement for explicit section-scoped authorship with source and destination IDs for every change. This makes the process unsuitable for rapid, undocumented patches that bypass doctrine checks and audit reconciliation.