Skip to content

Maintain Answer Lifecycle

Before you begin

Roles required: Governance lead, content strategist, support engineer.

This task applies after an answer has been published to the registry in APPROVED status. You need the answer_id of the answer you are acting on. All lifecycle operations are write actions — confirm you have the appropriate role before proceeding.

Assumed state: At least one answer is published in APPROVED status. See Publish an Approved Answer to the Registry.

Context

Approved answers must be maintained over time. Knowledge changes: products evolve, policies are updated, and sources become stale. The registry provides four post-publication lifecycle actions: supersede, retire, dispute, and review-and-renew. Each action is designed for a specific situation. Using the wrong action can result in knowledge gaps or loss of audit continuity.

Supersede an answer (update answer text or evidence)

Use supersede when the answer is no longer accurate and needs to be replaced with corrected or updated content.

1. POST to the supersede endpoint

curl -s -X POST http://localhost:8000/v1/registry/answers/ans_01j2k3l4m5n6p7q8r9w4/supersede \
  -H "Content-Type: application/json" \
  -d '{
    "answer_text": "The platform supports SSO via SAML 2.0, OIDC, and SCIM provisioning. Supported identity providers include Azure AD, Okta, Ping Identity, and OneLogin.",
    "evidence_links": [
      "https://heretto.atlassian.net/wiki/spaces/PROD/pages/12345",
      "https://heretto.atlassian.net/wiki/spaces/PROD/pages/67890"
    ],
    "review_due": "2027-06-07",
    "rationale": "OneLogin support added in v3.4 release. SCIM provisioning now GA."
  }'

2. Understand what happens

  • The original answer (ans_01j2k3l4m5n6p7q8r9w4) status changes to SUPERSEDED
  • A new answer is created with a new answer_id and version incremented to v+1
  • The new answer has a supersedes_id field pointing to the old answer's ID
  • The version chain is preserved for audit — no history is lost

The new answer starts in APPROVED status and is immediately available for readouts and retrieval.

Important: Use supersede — not retire — when the answer is incorrect or outdated. Retire is for answers that are no longer relevant at all (the product feature was removed, the question is no longer asked). Retiring an incorrect answer removes it from readouts without replacing it, leaving a knowledge gap. Always supersede first if the correct answer is known.

Retire an answer (remove from active use)

Use retire when an answer is no longer relevant — the underlying feature, policy, or context no longer exists — and there is no replacement.

1. POST to the retire endpoint

curl -s -X POST http://localhost:8000/v1/registry/answers/ans_01j2k3l4m5n6p7q8r9w4/retire \
  -H "Content-Type: application/json" \
  -d '{
    "rationale": "Legacy SSO feature was removed in v4.0. Replaced by unified identity management. No direct successor answer."
  }'

2. Understand what happens

  • The answer status changes to RETIRED
  • The answer is no longer surfaced in readouts or standard registry queries
  • The record is retained in the registry for audit; it can be retrieved by explicitly querying for retired answers
  • There is no new version created — the version chain ends here

Dispute an answer (flag for governance review)

Use dispute when you believe an answer may be incorrect or misleading but are not certain enough to supersede it immediately, or when a stakeholder challenges a published claim.

1. POST to the dispute endpoint

curl -s -X POST http://localhost:8000/v1/registry/answers/ans_01j2k3l4m5n6p7q8r9w4/dispute \
  -H "Content-Type: application/json" \
  -d '{
    "rationale": "Engineering team reports that OneLogin support was experimental only. Needs verification before claiming GA support."
  }'

2. Understand what happens

  • The answer status changes to DISPUTED
  • The answer is excluded from standard readouts by default
  • When include_disputed: true is set in a readout request, the answer is included but shown as a warning
  • A new validation assignment is created automatically, returning the candidate to IN_REVIEW
  • Once the new validation assignment is resolved (approved or revised), the answer either returns to APPROVED (if confirmed) or a superseding answer is published

Review and renew an answer approaching its review due date

Every published answer has a review_due date. When an answer is within 30 days of that date:

  • It appears in readouts with an expiry warning
  • It appears in the governance dashboard under the expiring-soon count

1. Identify expiring answers

Review your readout output or the governance dashboard for expiry warnings. The warning includes the answer_id and review_due date.

2. Review the answer for accuracy

Retrieve the answer and assess whether the content is still accurate:

curl -s "http://localhost:8000/v1/registry/answers/ans_01j2k3l4m5n6p7q8r9w4"

3. Act based on your assessment

Assessment Action
Answer is still accurate Supersede with the same text but a new review_due date
Answer is partly outdated Supersede with corrected text and new review_due
Answer is no longer relevant Retire
Accuracy is uncertain Dispute

Do not let answers expire without review. Expired answers continue to appear in readouts but with increasingly prominent staleness warnings.

Answer lifecycle state diagram

stateDiagram-v2
    [*] --> APPROVED : publish to registry
    APPROVED --> SUPERSEDED : supersede\n(new version created)
    APPROVED --> RETIRED : retire\n(no longer relevant)
    APPROVED --> DISPUTED : dispute\n(accuracy challenged)
    DISPUTED --> IN_REVIEW : new validation assignment created
    IN_REVIEW --> APPROVED : validated and confirmed
    IN_REVIEW --> SUPERSEDED : validated with corrections\n(new version)
    SUPERSEDED --> [*] : version chain preserved
    RETIRED --> [*] : audit record retained

Result

The answer lifecycle is maintained with full auditability. Superseded answers preserve the version chain from v1 through every subsequent version. Retired answers remain as audit records. Disputed answers enter governance review. No history is lost at any stage.

See also: Publish an Approved Answer to the Registry; Claim and Decide a Validation Assignment; Generate a Pre-Meeting Readout