GitHub hygiene

GitHub hygiene

Goal

GitHub should stay clean and navigable: open issues represent current intent or short-lived execution work; everything else is closed with a pointer to this docs site or archived appropriately. Planning truth stays in Roadmap, not in long-lived GitHub epics that drift.

When to use

• Periodic tidying (monthly or after a large milestone).
• Before onboarding someone new.
• After migrating decisions into sylva-docs.

Day-to-day habits

• Close with context: when an issue is superseded by a doc or roadmap item, close it and comment with the canonical URL path (e.g. /roadmap/…, /agent-workflows/…).
• Labels: use a small, consistent set (type/priority/area)—avoid one-off labels that only applied years ago.
• Duplicates: close duplicates and link to the surviving thread or doc.

Legacy issues (one-time or periodic cleanup playbook)

Use this when old issues no longer reflect reality:

1. Triage in batches — filter by age (e.g. open > 12 months) or by label.
2. For each issue, choose:
   • Still relevant — leave open only if there is a clear next action within your horizon; otherwise convert intent into Roadmap or a doc and close the issue with a link.
   • Superseded by docs/roadmap — close with: Superseded by: <full docs URL path> (e.g. shipped behavior documented under User Manual).
   • Obsolete — close with: Obsolete / won't pursue: plus one line why (optional link to Repositories and workspace map if repo is legacy).
3. Never mass-close without a category comment (even one sentence per batch in a closing comment on the last issue or a meta-issue is acceptable for solo workflows).

Outdated or legacy repositories

Align with Repositories and workspace map:

• Archive on GitHub when the repo is read-only / reference-only—sets expectations for visitors.
• If the repo stays non-archived but is not actively developed, pin a short README note: maintenance mode, where active work moved, link to sylva-docs.
• Do not use stale repos as dumping grounds for new issues; file intent in sylva-docs roadmap or the correct active repo.

Cursor skill

Use sylva-github-hygiene when cleaning issues or aligning repo state with this page.