Skip to content

Article Cleanup Workflow (One Article at a Time)

Objective

Clean one in-use article per cycle, save it in production-ready form for ISR, and leave an explicit editorial trail for BFF migration.

Per-Article Workflow

  1. Select one article from docs/shared/editorial-cleanup-tracker.yaml where status: pending.
  2. Open the article markdown in docs/articles/<slug>.md. 2.1 If legacy naming is poor, use replacement flow:
  3. create a new replacement article with a new slug/filename
  4. keep old article active while replacement is being finalized
  5. switch collection references to replacement slug once ready
  6. then mark old one deprecated
  7. record mapping in docs/shared/article-migration-ledger.yaml
  8. Apply canonical cleanup:
  9. metadata normalization (title/subtitle/author/category/tone)
  10. author selected from docs/shared/pseudo-authors.yaml
  11. category selected from docs/shared/editorial-taxonomy.yaml categories list
  12. tags selected from docs/shared/editorial-taxonomy.yaml tags list
  13. heading structure normalization (#/##/###)
  14. content rewrite for clarity and consistency
  15. reference insertion under ## References
  16. hero image and alt text quality check
  17. Update frontmatter editorial status:
  18. editorial.status: cleaned
  19. editorial.cleanedAt: YYYY-MM-DD
  20. editorial.workflowNote: <short-non-sensitive-note>
  21. Update tracker entry for the same slug:
  22. status: cleaned
  23. append an item to trail[] with date/action/summary.
  24. Validate locally in ISR (target site page and article detail page).
  25. Commit with message:
  26. Clean article: <slug> (metadata/structure/references/media)

Cleanup Definition of Done

  • Metadata matches canonical contract.
  • Tone is explicitly labeled and consistent in body.
  • Body has coherent section hierarchy with no heading jumps.
  • References section exists and supports key claims.
  • Media links resolve and alt text is descriptive.
  • Tracker is updated with a trail record.
  • No real identity/credential data is stored in markdown or public tracker fields.

Fast Execution Rule

  • Work strictly in priority order from currently used app-suite collections.
  • Do not batch multiple article rewrites unless explicitly requested.
  • Close one article fully before opening the next.