revise
Skill0 starsChanged 3 months agoMITView on GitHub
Revise an existing spec based on feedback or correction
7 other projects use a version of this.
Adopted by
Most recently taken up by
- stormlightlabs/miretheir own version, first seen Nov 1, 2026
- korya/swd-skillstheir own version, first seen Nov 1, 2026
- helderberto/agent-skillstheir own version, first seen Oct 11, 2026
- hsantanna88/clo-authortheir own version, first seen Oct 9, 2026
- hugosantanna/clo-authortheir own version, first seen Oct 8, 2026
- bloxy-studios/shorts-studiotheir own version, first seen Oct 1, 2026
Used with
Projects with it also use submit and analyze.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
H-mmerSkillsubmit
Draft and submit a vulnerability report to the bug bounty platform. Reads scope.yaml for platform/program, uses brain + findings for content. Always drafts first for review.
Also in 3 projects that use this
AnthropicSkillanalyze
Answer data questions -- from quick lookups to full analyses. Use when looking up a single metric, investigating what's driving a trend or drop, comparing segments over time, or preparing a formal data report for stakeholders.
Also in 3 projects that use this
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- hsantanna88/clo-author★ 262same name
- hugosantanna/clo-author★ 262same name
- helderberto/agent-skills★ 19same name
- stormlightlabs/thunderus★ 4same name
- korya/swd-skills★ 2same name
- stormlightlabs/mire★ 1same name
- bloxy-studios/shorts-studio★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. 0 are common, 3 are distinctive, and 17 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
If $ARGUMENTS is empty, ?, or help: Print:
- Distinctive: line 39
Stop — do not execute any further steps.
- Very specific: line 44
Read docs/specs/NNN-*.md for the given spec number.
- Very specific: line 46
Stop and report: "Spec NNN is sealed (Lane B).
- Distinctive: line 47
Do NOT modify the sealed spec file in any way.
- Very specific: line 48
If this is a Lane A project (docs/compliance/profile.yaml absent): skip this check — Lane A specs can always be revised.
- Very specific: line 51
When revising a spec that carries an Approved-SHA: field in frontmatter, the field is no longer valid against the revised text and must be …
- Very specific: line 58
Read
docs/compliance/profile.yaml: If the file is absent: this is a Lane A FORGE-internal project — skip Spec 089's behavior for this … - Very specific: line 61
If Change-Lane: is Lane-B: PROCEED with Spec 089's existing behavior verbatim.
- Very specific: line 62
If Change-Lane: is hotfix, small-change, standard-feature, or process-only: SKIP Spec 089's behavior.
- Very specific: line 63
If Change-Lane: is missing or any other value (e.g., a typo like Lane_B): STOP.
- Very specific: line 70
If the gate proceeds (Lane B project, Change-Lane: Lane-B): remove the Approved-SHA: line from the spec's frontmatter and append a Revision …
- Very specific: line 72
If the gate skips (Lane A): no action — the spec doesn't carry an Approved-SHA: field.
- Very specific: line 74
If the gate halts (fail-closed): operator must set Change-Lane: explicitly before /revise can complete.
- Very specific: line 79
If no: stop and recommend creating a new spec instead.
- Very specific: line 98
If none of BV/E/R/SR/TC changed in this revision, do NOT call record-predicted — the audit log only records score-change events.
- Very specific: line 131
If docs/compliance/profile.yaml is absent, skip this step (Lane A project).
- Very specific: line 134
If new requirements/ACs added AND spec is implemented: reset status to approved.
- Distinctive: line 140
If clarification only (typos, wording, no new ACs): do not change status.
- Very specific: line 145
After writing the revision entry, check the SAME edit set: if the new Revision Log entry matches any trigger phrase — target, AC, …
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- forge:paths-note (Spec 575): process-state paths in this command (docs/specs,
docs/sessions, docs/decisions, docs/research, docs/process-kit, docs/backlog.md) are the
CLASSIC-DEFAULT spellings, not fixed locations. When the project configures forge.paths
(e.g. the `contained` layout), resolve each key before use — bash: `forge_path <key>`
(source ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/config.sh, forge_config_load AGENTS.md);
python: `${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py .../runtime_config.py path <key>`. -->Framework: FORGE
Revise an existing spec based on validation feedback or a correction.
If $ARGUMENTS is empty, ?, or help:
Print:
/revise — Apply a correction or change request to an existing spec.
Usage: /revise <spec-number> <description of change>
Arguments:
spec-number (required) — the spec to revise
description (required) — what needs to change and why
Behavior:
- Adds a dated revision entry to the spec
- Updates spec body and tracking files (spec docs, README, CHANGELOG, backlog)
- Does NOT edit implementation files — run /implement after to apply changes
- If new requirements/ACs are added to an `implemented` spec, resets status to `approved`
- Clarification-only edits (typos, wording) do not change status
Use when: human validation found an issue, a correction is needed, or
requirements within the spec's existing scope need updating.
Not for: new scope or a different problem (create a new spec instead).
Note: when revising a draft spec, /revise refreshes `valid-until:` to today
+ forge.spec.draft_validity_days (default 90) — explicit operator
engagement is the renewal signal (Spec 363).
See: docs/specs/README.md (governance), CLAUDE.md (spec lifecycle)Stop — do not execute any further steps.
- Parse $ARGUMENTS to extract the spec number and the change description.
- Read
docs/specs/NNN-*.mdfor the given spec number. 2b. Lane B sealed check (Spec 052): If the spec hasLane-B-Sealed:in its frontmatter:- Stop and report: "Spec NNN is sealed (Lane B). Sealed specs cannot be revised — they are frozen audit records. To change this spec's requirements, create a successor spec with
Supersedes: NNNin its frontmatter. Run/spec <description>and addSupersedes: NNNto the new spec's header." - Do NOT modify the sealed spec file in any way.
- If this is a Lane A project (
docs/compliance/profile.yamlabsent): skip this check — Lane A specs can always be revised.
- Stop and report: "Spec NNN is sealed (Lane B). Sealed specs cannot be revised — they are frozen audit records. To change this spec's requirements, create a successor spec with
[mechanical] Step 2c — Approved-SHA clear (Spec 089, lane-gated by Spec 344)
When revising a spec that carries an Approved-SHA: field in frontmatter, the field is no longer valid against the revised text and must be cleared so the next /implement can rewrite it.
>>> spec-344 lane-gate
LANE-GATE: Spec 089 Approved-SHA mechanism is Lane B only. Read these conditions in order:
- Read
Change-Lane:from the spec's frontmatter. Possible values:hotfix,small-change,standard-feature,process-only,Lane-B, missing, or unrecognized. - Read
docs/compliance/profile.yaml. If the file is absent: this is a Lane A FORGE-internal project — skip Spec 089's behavior for this Step entirely. No SHA computed, noApproved-SHA:written or verified or cleared, noGATE [spec-integrity]line, no override prompt. Proceed silently to the next Step. - If
docs/compliance/profile.yamlis present: the project declares Lane B usage. Now apply the predicate:- If
Change-Lane:isLane-B: PROCEED with Spec 089's existing behavior verbatim. Compute/verify/clear the SHA per the existing logic. - If
Change-Lane:ishotfix,small-change,standard-feature, orprocess-only: SKIP Spec 089's behavior. No GATE line, no prompt. Proceed silently. - If
Change-Lane:is missing or any other value (e.g., a typo likeLane_B): STOP. Do not proceed. EmitGATE [spec-integrity]: FAIL — Change-Lane missing or unrecognized ('<value>') under a Lane B compliance profile. Set Change-Lane explicitly before proceeding.HALT. Do not invoke the SHA logic. Do not transition status. Do not proceed to subsequent steps.
- If
This block is load-bearing prose — Claude reads it as instructions and follows the predicate. The fail-closed branch ("STOP. Do not proceed.") is imperative; do not soften the phrasing.
See: docs/process-kit/close-validator-coverage.md § Lane-gate sentinel — canonical source.
<<< spec-344 lane-gate
If the gate proceeds (Lane B project, Change-Lane: Lane-B): remove the Approved-SHA: line from the spec's frontmatter and append a Revision Log entry: YYYY-MM-DD: Approved-SHA cleared by /revise — pending re-write at next /implement.
If the gate skips (Lane A): no action — the spec doesn't carry an Approved-SHA: field.
If the gate halts (fail-closed): operator must set Change-Lane: explicitly before /revise can complete.
- Confirm the change is within the spec's existing scope:
- If yes: proceed.
- If no: stop and recommend creating a new spec instead. "This looks like new scope — use
/specto create a new spec."
- State what will change: which sections of the spec body need updating.
Make the changes to spec documents and tracking files only: a. Update the spec body to reflect the corrected state. b. Add a dated revision entry:
YYYY-MM-DD: Revised — <description of change>.c. Updatedocs/specs/CHANGELOG.md:- YYYY-MM-DD: Spec NNN revised — <description>.d. Do NOT edit implementation files (code, command.mdfiles in.claude/commands/, config). Implementation of revised scope requires/implement. e. Refreshvalid-until:(Spec 363): If the spec'sStatus:isdraft, rewrite the spec'svalid-until:field totoday + forge.spec.draft_validity_days(default 90 if the AGENTS.md key is absent). The pre-existing value is replaced, not preserved. If the spec lacksvalid-until:entirely (pre-backfill state or non-draft status), add it now using the same formula. IfStatus:is anything other thandraft, skip this sub-step silently —valid-until:is a draft-only concern. f. Score-Audit predicted record on score change (Spec 368): If this revision modifies any of BV / E / R / SR / TC, append a newpredictedrecord to the score-audit log via the shared helper. Do NOT inline JSON here.The helper exposes a
next-revise-roundsubcommand that derives the next round from the audit log:next_round=$(bash ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/score-audit.sh next-revise-round "$spec_id") bash ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/score-audit.sh record-predicted "$spec_id" "$bv" "$e" "$r" "$sr" "$tc" "$lane" "$kind_tag" "$next_round"(PowerShell parity: invoke
pwsh ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/score-audit.ps1 record-predicted ...with the same arguments.)If none of BV/E/R/SR/TC changed in this revision, do NOT call
record-predicted— the audit log only records score-change events. The helper is advisory; failures emit a WARN to stderr but never block/revise.See: docs/process-kit/score-calibration-loop.md.
- Lane B impact analysis — if
docs/compliance/profile.yamlexists (Lane B project): a. Read the compliance profile to identify active risk categories (e.g. safety, security, privacy, reliability). b. Assess each risk category against the revised spec content:safety: changes to safety functions, fail-safe behavior, or critical constraintssecurity: changes to authentication, authorization, data handling, or trust boundariesprivacy: changes to PII handling, data retention, or consent flowsreliability: changes to SLAs, fault tolerance, or recovery procedures c. Identify impacted traceability links: requirements, tests, and evidence items that reference the revised spec sections (cross-reference/traceoutput for the spec). d. Determine re-verification triggers: list any gates that must be re-run based on affected risk categories per profile rules. e. Classify overall impact:minor(no gates triggered) /moderate(1–2 non-safety gates) /major(3+ gates, or safety/security affected). f. Generate impact reportdocs/impact-reports/YYYY-MM-DD-NNN-impact.md:
# Impact Report — Spec NNN revision YYYY-MM-DD Spec: NNN — <title> Change: <description of change> Classification: minor | moderate | major ## Risk Categories Assessed | Category | Affected | Notes | |----------|----------|-------| | safety | yes/no | <why> | ... ## Impacted Traceability Links - <requirement/test/evidence item> → <why affected> ## Re-verification Requirements - Gates to re-run: <list> - Evidence to refresh: <list>- If
docs/compliance/profile.yamlis absent, skip this step (Lane A project).
- Status reset check — determine if this revision adds new requirements or ACs:
- If new requirements/ACs added AND spec is
implemented: reset status toapproved. a. UpdateStatus: approvedin the spec file. b. Update the spec's row indocs/specs/README.mdtoapproved. c. Update the spec's row indocs/backlog.mdtoapproved. d. Add a CHANGELOG entry noting the reset. e. Add a revision entry:YYYY-MM-DD: Status reset to approved — new scope requires /implement. - If clarification only (typos, wording, no new ACs): do not change status.
- If new requirements/ACs added AND spec is
- Report what was changed. If status was reset, remind: "Run
/implement NNNto deliver the new scope." Otherwise, remind to run/close NNN. If a Lane B impact report was generated, include the impact classification and any re-verification requirements in the report.
[mechanical] AC-drift nudge (Spec 583)
After writing the revision entry, check the SAME edit set: if the new Revision Log entry
matches any trigger phrase — target, AC, acceptance criteri, changed the goal,
now verifies, instead of (case-insensitive; the named set, Spec 583 AC3) — AND the
## Acceptance Criteria section was NOT modified in this revision, prompt:
Your revision note mentions a target/AC change but the Acceptance Criteria text is untouched.
Validators verify AC-as-written (Spec 546 pitfall rule #4) — a note-only change WILL fail at
/close. Edit the AC now? (yes/no)yes → collect the AC edit before finishing. no → append to the Revision Log:
AC-drift nudge declined — AC text intentionally unchanged. Silent when the AC section was
edited in the same revision, or no trigger phrase matches.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

