Title: Decision lifecycle management and archival system · Issue #85 · github/squad · GitHub
Open Graph Title: Decision lifecycle management and archival system · Issue #85 · github/squad
X Title: Decision lifecycle management and archival system · Issue #85 · github/squad
Description: Problem User feedback: "we have a LOOOOOOT of old decisions and stuff. i know we've done a good deal of purging but, could we do a lot, lot more? we might want to come up with some skills for managing decisions." Current state: decisions...
Open Graph Description: Problem User feedback: "we have a LOOOOOOT of old decisions and stuff. i know we've done a good deal of purging but, could we do a lot, lot more? we might want to come up with some skills for manag...
X Description: Problem User feedback: "we have a LOOOOOOT of old decisions and stuff. i know we've done a good deal of purging but, could we do a lot, lot more? we might want to come up with some skills ...
Opengraph URL: https://github.com/github/squad/issues/85
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Decision lifecycle management and archival system","articleBody":"## Problem\r\n\r\nUser feedback: \"we have a LOOOOOOT of old decisions and stuff. i know we've done a good deal of purging but, could we do a lot, lot more? we might want to come up with some skills for managing decisions.\"\r\n\r\nCurrent state:\r\n- `decisions.md` is 2,084 lines (as of 2026-02-16)\r\n- Contains decisions spanning from 2026-02-07 through present (10+ days of rapid iteration)\r\n- No archival or lifecycle management\r\n- Scribe's consolidation helps but doesn't remove obsolete decisions\r\n- Every agent reads the FULL decisions.md on spawn → large context cost\r\n\r\n## Proposal: Decision Lifecycle & Archival\r\n\r\nCreate a skill for Scribe: **decision-management** with lifecycle stages:\r\n\r\n### 1. Active Decisions (current decisions.md)\r\n- Recent decisions (last 30 days by default)\r\n- High-impact architectural/policy decisions regardless of age\r\n- Decisions explicitly marked `status: permanent`\r\n\r\n### 2. Archived Decisions (new: decisions/archive/)\r\n- Decisions older than 30 days that aren't permanent\r\n- One-time decisions (e.g., \"shipped v0.1.0\", \"merged PR #5\")\r\n- Implementation details that are now in code\r\n- Organized by quarter: `decisions/archive/2026-Q1.md`\r\n\r\n### 3. Obsolete/Superseded\r\n- Decisions explicitly superseded by later decisions\r\n- Moved to archive with `[SUPERSEDED by 2026-02-15: {new decision}]` markers\r\n- Never deleted — kept for historical context\r\n\r\n## Decision Criteria\r\n\r\n**Keep in main decisions.md:**\r\n- [ ] Referenced in last 30 days (actively being applied)\r\n- [ ] Architectural foundation (affects how agents think about the system)\r\n- [ ] Team policy/workflow (e.g., proposal-first, branch model, release process)\r\n- [ ] Explicitly marked `status: permanent` by Lead or user\r\n\r\n**Archive to decisions/archive/:**\r\n- [ ] Older than 30 days AND not referenced recently\r\n- [ ] Completed one-time tasks (\"shipped X\", \"fixed bug Y\")\r\n- [ ] Implementation details now encoded in code/docs\r\n- [ ] Historical context valuable for audit but not day-to-day work\r\n\r\n**Example active decisions:**\r\n- Proposal-first workflow (team policy — permanent)\r\n- Skills system adoption (architectural — permanent) \r\n- Branching strategy (team policy — permanent)\r\n- Release process (team policy — permanent)\r\n\r\n**Example archived decisions:**\r\n- \"Shipped v0.1.0\" (one-time event)\r\n- \"Fixed Scribe resilience bug\" (implementation detail now in code)\r\n- \"Cleaned up decisions.md on 2026-02-08\" (meta-task)\r\n- Early platform decisions superseded by later ones\r\n\r\n## Scribe Skill: decision-management\r\n\r\n**When to run:** During session logging, after merging inbox\r\n**What it does:**\r\n1. Read decisions.md\r\n2. Identify candidates for archival (> 30 days old, not permanent, completed/historical)\r\n3. Move qualified decisions to `decisions/archive/{YYYY-QX}.md`\r\n4. Add forward references in archive: \"See decisions.md for current policy\"\r\n5. Add backward references in decisions.md: \"Historical decisions: see decisions/archive/\"\r\n6. Report: \"Archived 12 decisions from Q1 — decisions.md now 800 lines (was 2084)\"\r\n\r\n**Safeguards:**\r\n- Never archives decisions marked `status: permanent`\r\n- Prompts user before first archival: \"Archive 15 old decisions? [y/n]\"\r\n- Generates summary of what will be archived for review\r\n- Dry-run mode: `squad scribe --archive-decisions --dry-run`\r\n\r\n## Why This Matters\r\n\r\n- **Context cost:** Agents read full decisions.md on every spawn. 2K lines = high token cost.\r\n- **Signal-to-noise:** New agents need foundational decisions, not \"we fixed bug #42 in v0.1.1\"\r\n- **Performance:** Smaller decisions.md = faster agent spawns\r\n- **Maintainability:** Easier to onboard new agents/humans when decisions are curated\r\n- **Audit trail:** Archive preserves history without cluttering active decisions\r\n\r\n## Alternatives Considered\r\n\r\n1. **Hard limits:** \"decisions.md must be \u003c 500 lines\" → rejected, too arbitrary\r\n2. **Delete obsolete decisions:** Rejected — lose historical context and audit trail\r\n3. **Split by category:** Rejected —agents need cohesive view, not category hunting\r\n4. **Time-based only:** Keep recent, archive old — CHOSEN, simple and predictable\r\n\r\n## Acceptance Criteria\r\n\r\n- [ ] `.ai-team/decisions/archive/{YYYY-QX}.md` directory structure\r\n- [ ] Scribe skill: decision-management with archival logic\r\n- [ ] CLI command: `squad scribe --archive-decisions [--dry-run]`\r\n- [ ] 30-day default threshold (configurable via team.md)\r\n- [ ] `status: permanent` tag in decision format to prevent archival\r\n- [ ] Migration: archive appropriate decisions from current 2K line decisions.md\r\n- [ ] Test: verify agents still find decisions after archival (via grep or semantic search fallback to archive)\r\n- [ ] Docs: document decision lifecycle in docs/features/memory.md\r\n\r\n## Out of Scope (Defer to v0.6.0+)\r\n\r\n- Semantic search across archived decisions (LLM-powered \"find similar past decisions\")\r\n- Decision dependency graph (\"this decision built on these prior decisions\")\r\n- Version history per decision (decisions.md is append-only, we rely on git history)\r\n","author":{"url":"https://github.com/bradygaster","@type":"Person","name":"bradygaster"},"datePublished":"2026-02-16T19:40:54Z","url":"https://github.com/github/squad/issues/85"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:6a41905b-da50-3d24-7cf0-4bf54284b706 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | E33E:38E318:1311A6E:1809498:6B015C1E |
| html-safe-nonce | e74ee0b1f6a91cc528ca80acaab6fac2a5314eeab4f9703c4345bd1c7eda9e83 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFMzNFOjM4RTMxODoxMzExQTZFOjE4MDk0OTg6NkIwMTVDMUUiLCJ2aXNpdG9yX2lkIjoiNzg3MzM1NDMxNzMyNjAxNTUxOCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | f09eefc322cf432e6311872e7cd2236ca5aa81c7ddfe8eb0d9afe13887a8e1f3 |
| hovercard-subject-tag | issue:3949273383 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/85/issue_layout |
| twitter:image | https://opengraph.githubassets.com/6ff31d8dd49b337233c9528a0f827155d27bdadca953da2665c51785bdef5314/github/squad/issues/85 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/6ff31d8dd49b337233c9528a0f827155d27bdadca953da2665c51785bdef5314/github/squad/issues/85 |
| og:image:alt | Problem User feedback: "we have a LOOOOOOT of old decisions and stuff. i know we've done a good deal of purging but, could we do a lot, lot more? we might want to come up with some skills for manag... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | bradygaster |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/github/squad git https://github.com/github/squad.git |
| octolytics-dimension-user_id | 9919 |
| octolytics-dimension-user_login | github |
| octolytics-dimension-repository_id | 1151205052 |
| octolytics-dimension-repository_nwo | github/squad |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1151205052 |
| octolytics-dimension-repository_network_root_nwo | github/squad |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width