Fdr

Feature Decision Records

Describe non-obvious feature behavior as it exists today and why it works that way.

Classify first

Create or update an FDR when implemented user-visible behavior or a feature-specific design choice changes, including:

• behavior users or operators can observe;
• permissions or role differences within a feature;
• a feature-local constraint, fallback, or failure mode;
• a non-obvious product choice whose rationale should survive implementation changes.

Use an ADR for cross-cutting architecture such as trust boundaries, authorization models, persistence, providers, deployment, or recovery. Use no decision record for a local implementation detail, ordinary refactor, dependency patch, or bug fix that restores already-recorded behavior.

An FDR is not a code walkthrough, API schema, runbook, implementation plan, changelog, or promise of future work.

Read narrowly

1. Follow the repository's instruction files and discovery conventions.
2. Read docs/fdr/INDEX.md when it exists.
3. Read only related FDRs and constraining ADRs.
4. Verify behavior in current implementation, tests, configuration, and user or operations documentation.
5. Require release or rollout evidence before marking retrospective work Active.

Source documents identify candidates and rationale. They do not prove current behavior by themselves. Planned, partial, or staging-only work cannot be Active.

For retrospective work, do not use Draft as a substitute for missing implementation or release evidence. Leave the candidate unresolved. Draft is only for qualifying behavior in a current implementation or review change.

Operations

Create

Use the next unused three-digit ID from docs/fdr/INDEX.md and existing filenames. Create docs/fdr/FDR-NNN-kebab-case-title.md and add it to the index in the same change.

Update

Rewrite the affected current-state section when behavior changes. Update its rationale, tradeoff, evidence, related records, last-reviewed date, and index row as needed. Do not append a chronological changelog.

Retire

Mark an FDR Retired only after current implementation and release evidence show the feature is no longer supported. Keep the record and index row as history.

Audit

Compare selected FDRs with current behavior and release evidence. Report confirmed, drifted, retired, planned-only, and unresolved records. Do not silently edit records unless the user also authorized changes.

Backfill preview

Invoke as backfill preview [sources...].

This mode is read-only:

1. If sources are supplied, use only those sources for candidate discovery unless the user permits broader discovery. Required verification of current code, configuration, tests, permissions, and release evidence remains in scope.
2. Otherwise, discover likely history under docs/superpowers/specs/, docs/superpowers/plans/, product or feature documentation, runbooks, release notes, and any production plan referenced by repository instructions.
3. Verify candidates against current code, tests, configuration, permissions, and release evidence as applicable.
4. Return the sources consulted and group candidates as confirmed, rejected, duplicate, planned-only, or unresolved.
5. For each confirmed candidate, propose a title, current status, related ADRs, and supporting evidence.
6. Store a JSON preview manifest under $(git rev-parse --git-common-dir)/decision-previews/ using the exact schema below. Do not reserve record IDs.

Do not create records, update indexes, reserve IDs, or edit source documents in preview mode. The manifest is the preview's only file write and lives outside the working tree. Report its path and SHA-256 digest so the user can review and authorize that exact candidate set.

Preview manifest schema

Use these exact snake_case fields so another supported agent can validate and apply the same manifest:

{
  "format_version": 2,
  "record_type": "FDR",
  "operation": "backfill-preview",
  "created_at": "ISO-8601 UTC timestamp",
  "repository": {
    "identity": "origin URL, or absolute repository root when no origin exists",
    "head": "full Git commit SHA"
  },
  "discovery_sources": [{ "path": "repository-relative POSIX path or canonical file URI", "sha256": "hex" }],
  "verification_evidence": [{ "path": "repository-relative POSIX path or canonical file URI", "sha256": "hex" }],
  "record_snapshot": {
    "entries": [{ "path": "repository-relative path", "sha256": "hex" }],
    "aggregate_sha256": "hash of the ordered path and content-hash entries"
  },
  "candidates": [{
    "key": "stable preview-local key",
    "classification": "confirmed | rejected | duplicate | planned-only | unresolved",
    "proposed_title": "title or null",
    "proposed_status": "Active | Retired | null",
    "related_adrs": ["ADR-NNN"],
    "evidence_paths": ["repository-relative POSIX path or canonical file URI"]
  }],
  "record_ids_reserved": false
}

For a file inside the repository, path is its normalized POSIX path relative to the repository root. For an external file explicitly supplied by the user or referenced by repository instructions, resolve symlinks with the platform realpath operation and encode that absolute path as an RFC 8089 file: URL; that URL is path. Files within the repository still use the repository form, even if supplied by absolute path. Expand a supplied directory to the regular files actually consulted and record each file separately. Reject other URI schemes, relative paths that escape the repository, a file URL that does not round-trip to the same realpath, and external files that were neither supplied nor referenced. Apply resolves each entry by these rules and hashes its bytes again before writing.

For a confirmed candidate, proposed_title and proposed_status are non-null, related_adrs contains sorted unique existing ADR identifiers or is empty, and evidence_paths is non-empty. For every other classification, proposed_status is null and related_adrs is empty. These fields remain in every candidate object so ADR and FDR manifests have the same field names.

record_snapshot.entries must be a complete sorted inventory of docs/fdr/, including docs/fdr/INDEX.md; additions and removals must therefore change the aggregate hash. Sort entries bytewise by path, encode each as UTF-8 <path>\t<sha256>\n, concatenate without a header or trailing data beyond each entry's newline, and SHA-256 that byte sequence. Producers and validators must use this exact serialization.

Backfill apply

Invoke as backfill apply <manifest-path> --manifest-sha256 <sha256> --authorize <key>[,<key>...] only when the user supplies that exact command or explicitly approves its exact path, digest, and unique comma-separated candidate-key set. Treat the authorization list as a set; it may be a strict subset of confirmed candidates, but every key must be confirmed in the manifest. Do not rediscover candidates during apply.

Before parsing or writing, hash the exact manifest bytes and require an exact match with --manifest-sha256. Then reject a missing or malformed manifest (including unknown or missing schema fields), the wrong repository or record type, duplicate authorization keys, any changed discovery-source or verification-evidence hash, any changed record/index snapshot, or any authorized key that is not confirmed. The records written must match the authorized key set exactly. A stale or mismatched manifest requires a new preview; do not repair it in place. Allocate IDs at write time and update the index atomically in the same change. Omit unresolved, duplicate, planned-only, unverified, and confirmed-but-unauthorized candidates. Applying a subset makes the snapshot stale, so remaining candidates require a new preview.

Record format

# FDR-NNN: Feature title

**Status:** Draft | Active | Retired
**Last reviewed:** YYYY-MM-DD

## Overview

What the feature provides and who it serves.

## Behavior

- Current user-visible behavior and important failure modes.

## Design Decisions

### Decision title

**Decision:** The chosen feature behavior.

**Why:** The user, product, security, or operational reason.

**Tradeoff:** What this choice costs or deliberately omits.

## Related

- **ADRs:** [ADR-NNN](../adr/ADR-NNN-title.md)
- **FDRs:** Related feature records, when useful.

## Evidence

- [Current implementation](relative/path)
- [Behavior test](relative/path)
- [Release or operational evidence](relative/path)

When roles or access materially affect behavior, add this optional section between Design Decisions and Related:

## Permissions

- The relevant role or access difference.

Do not add Permissions otherwise. Use repository-relative links. Keep operational steps and implementation detail in their existing documents and link them instead of copying them.

Completion checks

• The decision meets the FDR threshold rather than the ADR threshold.
• Behavior is current and supported by implementation and tests.
• Active status has release evidence.
• Required sections are present with no unresolved placeholders.
• Each non-obvious choice states Decision, Why, and Tradeoff.
• Permissions appears only when access materially affects behavior.
• Related ADR links resolve.
• docs/fdr/INDEX.md contains exactly one matching row.
• For a current feature decision, the record changes in the same pull request as the qualifying behavior. A retrospective backfill instead requires historical implementation and release evidence through its authorized manifest.
• A backfill apply is bound to one valid, unchanged, explicitly authorized preview manifest.
• Every validation command required by the repository's governing instructions passes; running only a subset is not completion.