Skip to content
Forgeplan

forgeplan deprecate

forgeplan deprecate moves an artifact from active (or stale) to deprecated — a terminal state. Unlike supersede, deprecation does not point at a replacement: you are saying “this decision no longer applies and nothing is taking its place.” The --reason flag is required so future readers understand why the artifact was retired, and the artifact itself is preserved so historical links keep resolving.

When to use

Section titled “When to use”
  • A business pivot made a PRD irrelevant: the feature was cancelled and there is no follow-up PRD.
  • A ProblemCard was closed because the underlying issue disappeared (environment changed, workaround became permanent) and no SolutionPortfolio is needed.
  • A constraint ADR no longer applies: the technology it governed has been removed from the stack entirely.
  • A stale artifact was reviewed and the team decided it should not be renewed — the validity genuinely expired.

When NOT to use

Section titled “When NOT to use”
  • You have a direct replacement — use forgeplan supersede with --by so the lineage is tracked.
  • You want to re-evaluate the decision in a fresh draft — use forgeplan reopen, which combines deprecation with creation of a successor draft.
  • The artifact is still in draft — drafts that were never activated can be removed or rewritten, not deprecated.
  • You only need to extend validity on a stale artifact — use forgeplan renew.

Usage

Section titled “Usage”
forgeplan deprecate --reason <REASON> <ID>

Arguments

Section titled “Arguments”
  <ID>  Artifact ID

Options

Section titled “Options”
      --reason <REASON>  Reason for deprecation
  -h, --help             Print help
  -V, --version          Print version

Examples

Section titled “Examples”

Example 1: Retire a cancelled PRD

Section titled “Example 1: Retire a cancelled PRD”
Terminal window
forgeplan deprecate PRD-011 --reason "feature cancelled after Q1 roadmap review, no successor"

PRD-011 enters deprecated. Health reports exclude it from blind-spot calculations but it remains readable.

Example 2: Close an obsolete ProblemCard

Section titled “Example 2: Close an obsolete ProblemCard”
Terminal window
forgeplan deprecate PROB-018 --reason "root cause removed by infra migration, problem no longer reproducible"

ProblemCards don’t run the MUST gate on activation, but deprecation still records the terminal reason.

Example 3: Deprecate a stale ADR that will not be renewed

Section titled “Example 3: Deprecate a stale ADR that will not be renewed”
Terminal window
forgeplan stale
forgeplan deprecate ADR-009 --reason "valid_until expired 2026-03; architecture replaced by RFC-014 scope"

Use forgeplan stale to find expired artifacts, then deprecate the ones that shouldn’t be renewed.

How it fits the workflow

Section titled “How it fits the workflow”

Deprecation is a clean, terminal ending: the artifact leaves the active set and stops influencing forgeplan health. It is the right tool when a decision’s relevance has genuinely ended and no successor exists. Because the state is terminal, the reason you pass becomes the permanent explanation — write it for a reader six months from now, not for yourself today.

Common errors

Section titled “Common errors”
ErrorCauseFix
--reason is requiredFlag omittedPass --reason "..." with a human-readable explanation
Cannot deprecate from draftArtifact was never activatedDelete or rewrite the draft instead
Already in terminal stateAlready deprecated or supersededTerminal states are final — nothing to do
Blind spots increased after deprecationActive artifacts depended on this oneUpdate or supersede dependents before deprecating

See also

Section titled “See also”