agentleFS
Renozoic-FoundryRenozoic-Foundry/forge-public/.claude/skills/revise/SKILL.md

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

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-mmerSkill

    submit

    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

  • AnthropicSkill

    analyze

    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

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
  1. Very specific:

    If $ARGUMENTS is empty, ?, or help: Print:

    line 17
  2. Distinctive:

    Stop — do not execute any further steps.

    line 39
  3. Very specific:

    Read docs/specs/NNN-*.md for the given spec number.

    line 44
  4. Very specific:

    Stop and report: "Spec NNN is sealed (Lane B).

    line 46
  5. Distinctive:

    Do NOT modify the sealed spec file in any way.

    line 47
  6. Very specific:

    If this is a Lane A project (docs/compliance/profile.yaml absent): skip this check — Lane A specs can always be revised.

    line 48
  7. Very specific:

    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 …

    line 51
  8. Very specific:

    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 …

    line 58
  9. Very specific:

    If Change-Lane: is Lane-B: PROCEED with Spec 089's existing behavior verbatim.

    line 61
  10. Very specific:

    If Change-Lane: is hotfix, small-change, standard-feature, or process-only: SKIP Spec 089's behavior.

    line 62
  11. Very specific:

    If Change-Lane: is missing or any other value (e.g., a typo like Lane_B): STOP.

    line 63
  12. Very specific:

    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 …

    line 70
  13. Very specific:

    If the gate skips (Lane A): no action — the spec doesn't carry an Approved-SHA: field.

    line 72
  14. Very specific:

    If the gate halts (fail-closed): operator must set Change-Lane: explicitly before /revise can complete.

    line 74
  15. Very specific:

    If no: stop and recommend creating a new spec instead.

    line 79
  16. Very specific:

    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.

    line 98
  17. Very specific:

    If docs/compliance/profile.yaml is absent, skip this step (Lane A project).

    line 131
  18. Very specific:

    If new requirements/ACs added AND spec is implemented: reset status to approved.

    line 134
  19. Distinctive:

    If clarification only (typos, wording, no new ACs): do not change status.

    line 140
  20. Very specific:

    After writing the revision entry, check the SAME edit set: if the new Revision Log entry matches any trigger phrase — target, AC, …

    line 145

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- 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.


  1. Parse $ARGUMENTS to extract the spec number and the change description.
  2. Read docs/specs/NNN-*.md for the given spec number. 2b. Lane B sealed check (Spec 052): If the spec has Lane-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: NNN in its frontmatter. Run /spec <description> and add Supersedes: NNN to 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.yaml absent): skip this check — Lane A specs can always be revised.

[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:

  1. Read Change-Lane: from the spec's frontmatter. Possible values: hotfix, small-change, standard-feature, process-only, Lane-B, missing, or unrecognized.
  2. 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, no Approved-SHA: written or verified or cleared, no GATE [spec-integrity] line, no override prompt. Proceed silently to the next Step.
  3. If docs/compliance/profile.yaml is present: the project declares Lane B usage. Now apply the predicate:
    • If Change-Lane: is Lane-B: PROCEED with Spec 089's existing behavior verbatim. Compute/verify/clear the SHA per the existing logic.
    • If Change-Lane: is hotfix, small-change, standard-feature, or process-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 like Lane_B): STOP. Do not proceed. Emit GATE [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.

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.

  1. 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 /spec to create a new spec."
  2. State what will change: which sections of the spec body need updating.
  3. 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. Update docs/specs/CHANGELOG.md: - YYYY-MM-DD: Spec NNN revised — <description>. d. Do NOT edit implementation files (code, command .md files in .claude/commands/, config). Implementation of revised scope requires /implement. e. Refresh valid-until: (Spec 363): If the spec's Status: is draft, rewrite the spec's valid-until: field to today + 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 lacks valid-until: entirely (pre-backfill state or non-draft status), add it now using the same formula. If Status: is anything other than draft, 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 new predicted record to the score-audit log via the shared helper. Do NOT inline JSON here.

    The helper exposes a next-revise-round subcommand 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.

  4. Lane B impact analysis — if docs/compliance/profile.yaml exists (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 constraints
    • security: changes to authentication, authorization, data handling, or trust boundaries
    • privacy: changes to PII handling, data retention, or consent flows
    • reliability: 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 /trace output 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 report docs/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.yaml is absent, skip this step (Lane A project).
  5. Status reset check — determine if this revision adds new requirements or ACs:
    • If new requirements/ACs added AND spec is implemented: reset status to approved. a. Update Status: approved in the spec file. b. Update the spec's row in docs/specs/README.md to approved. c. Update the spec's row in docs/backlog.md to approved. 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.
  6. Report what was changed. If status was reset, remind: "Run /implement NNN to 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.