Skip to main content

Runbook: Portfolio Archival Procedure

Quick Reference​

ScenarioDeprecating or archiving portfolio content
SeverityLow (planned maintenance)
MTTR TargetN/A (planned work)
On-CallNo
EscalationPortfolio owner if policy conflicts arise

Overview​

This runbook defines the steps to archive portfolio content while preserving evidence integrity. Use it whenever a project or document is no longer representative but must remain traceable.

When to use this runbook:

  • A project is no longer active or representative
  • Evidence artifacts must be retired without breaking links
  • Governance policy requires archival rather than removal

When NOT to use this runbook:

  • Minor documentation edits (use normal PR workflow)
  • Emergency changes (use relevant incident runbooks)

Prereqs / Inputs​

  • Portfolio eligibility criteria
  • Portfolio archival policy
  • Portfolio change intake checklist
:::warning
If archival would break evidence links or remove required artifacts, stop and update the policy before proceeding.
:::

Procedure / Content​

1) Confirm context​

  • Identify the content to be archived
  • Confirm the reason matches archival triggers
  • List all inbound links (dossiers, ADRs, runbooks, release notes)

2) Prepare archival updates​

  • Add an archival notice to the affected page(s)
  • Update any index pages to mark the item as archived
  • Ensure a replacement link or rationale is documented

3) Update governance artifacts​

  • Update the release notes index with the archival entry
  • Add a release note describing the archival decision
  • Update the roadmap if the archive affects phase status
  • Run local link checks (pnpm build in portfolio-docs)
  • Confirm no broken links or missing references

5) Merge and publish​

  • Open a PR with evidence and rationale
  • After merge, deploy docs and verify navigation

Validation / Expected outcomes​

  • Archived content remains accessible and clearly labeled
  • No broken links in docs build
  • Release notes capture the archival decision

If validation fails, revert the archival changes and correct links before retrying.

Rollback / Recovery​

Rollback trigger conditions​

  • Broken links detected after archival
  • Reviewer path no longer resolves to evidence

Rollback procedure​

  • Revert the PR
  • Restore the archived content and index links
  • Re-run pnpm build and confirm integrity

Failure modes / Troubleshooting​

  • Broken links: identify inbound references and add archival notes or redirects
  • Missing release note: add a release note before re-attempting

References​