القائمة
WHEN: A decision is being superseded, deprecated, or has aged out. Archive it without deletion — marks as warm→cold→archived with full audit trail.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
WHEN: You need to detect performance regressions before merge — TTFB, response time, bundle size. Run as part of forge-eval-gate or standalone before raising a PR.
WHEN: You are writing a new decision, superseding an old one, or querying relationships across decisions. Create semantic edges between decisions and link concepts across products/projects/time.
WHEN: You are about to make a decision and need to check if prior art or past learnings exist. Recall decisions, patterns, and gotchas from the brain before proceeding.
WHEN: You need to trace the full provenance of a specific decision — who made it, when, why, and what alternatives were considered. Shows why, when, by whom, evidence, alternatives, outcome.
WHEN: You need to record a decision, lock a spec, log an eval run, or document learnings in the brain.
WHEN: A deploy has just completed and you need to monitor the live app for anomalies — console errors, screenshot regressions, unexpected responses. Run post-deploy, before marking deploy complete.
| name | brain-forget |
| description | WHEN: A decision is being superseded, deprecated, or has aged out. Archive it without deletion — marks as warm→cold→archived with full audit trail. |
| type | flexible |
| requires | ["brain-read"] |
| version | 1.0.0 |
| preamble-tier | 2 |
| triggers | ["remove a decision","delete brain entry","forget a decision","archive brain file"] |
| allowed-tools | ["Bash","Write"] |
| Rationalization | Why It Fails |
|---|---|
| "This decision is wrong, I'll just delete it" | Deletion destroys audit trail. Demote to archived — wrong decisions teach as much as right ones. |
| "It's old, so it's irrelevant" | Age alone doesn't determine relevance. A 2-year-old API versioning decision may still be the canonical pattern. Check dependents before demoting. |
| "I'll archive everything from that product" | Bulk archival skips per-decision evaluation. Some decisions from a deprecated product may apply to active products. |
| "Archived decisions don't need commit messages" | Every status change needs a commit explaining why. "Cleaned up old decisions" is not a reason — state what changed and why. |
| "I'll demote it straight to archived" | The demotion lifecycle exists to catch premature archival. Active → Warm → Cold → Archived. Each step requires evidence. |
If you are thinking any of the above, you are about to violate this skill.
NEVER DELETE A DECISION. EVERY DEPRECATED DECISION MUST BE ARCHIVED WITH ITS FULL CONTEXT, DEMOTION REASON, AND LESSONS LEARNED COMMITTED TO GIT SO THE AUDIT TRAIL IS PERMANENTLY PRESERVED.
If you notice any of these, STOP and do not proceed:
archived status with a commit explaining why.Archive old or deprecated decisions without deletion. Implements a demotion lifecycle: Active → Warm → Cold → Archived. All decisions remain auditable and searchable by status.
The brain actively demotes decisions through five distinct rules, each with clear triggers, approval requirements, and communication protocols. A decision can be triggered by multiple rules; the earliest applies.
Trigger: Natural aging period reached
Who triggers: Automated system (scheduled job), no human approval needed for time-based transitions
Evidence required:
Dependent decisions: Grandchildren (decisions that reference this one) remain Active. Parent demotion does not automatically demote children.
Communication:
Trigger: New decision replaces old one
Who triggers: Decision author or team lead (explicit action required)
Evidence required:
Dependent decisions:
successor: [ID] field for easy lookupCommunication:
Example:
status: Cold
status_reason: superseded_by
successor: D89
successor_title: Header-Based API Versioning
deprecation_timeline: |
- 2026-12-15: D89 published (this decision marked Cold)
- 2027-03-15: Teams should begin migration
- 2027-06-15: Support for D42 approach ends
migration_path: "See D89 for step-by-step migration guide"
Trigger: Decision no longer applies due to changed context
Who triggers: Domain expert or council member (approval required from decision stakeholder)
Evidence required:
Dependent decisions:
Communication:
Example:
status: Cold
status_reason: outdated
validity_trigger: System constraint changed
changed_context: |
- 2026-08-01: Migrated from PostgreSQL to MySQL
- Old decision assumed full JSONB support (PostgreSQL-specific feature)
- MySQL JSON type lacks JSONB operators used in D42 implementation
- Dependents should review and adapt if needed
dependents_flagged: [D67, D78, D91]
recommended_action: Review D67, D78, D91 for compatibility with new constraint
Trigger: Experiment concluded, pattern validated or rejected
Who triggers: Experiment owner or engineering lead (approval required)
Evidence required:
Dependent decisions:
Communication:
Example Rejection:
status: Cold
status_reason: experimental_end
experiment_dates: "2026-01-15 to 2026-06-15"
metrics: |
- Client adoption: 2% (target was 15%)
- Developer satisfaction: 3.2/5 (threshold: 4.0)
- Support requests: 300+ issues (target: <50)
decision: Rejected pattern doesn't meet adoption threshold
lessons: |
- Clients prefer existing approach (simpler, familiar)
- Onboarding overhead too high for marginal benefit
- Maintenance burden unsustainable at scale
alternative: Continue using D42 approach; revisit in 12 months if needs change
Example Adoption:
status: Active (graduated from experimental)
status_reason: experimental_end
experiment_dates: "2026-01-15 to 2026-06-15"
metrics: |
- Performance improvement: 35% (target 20%)
- Developer adoption: 87% (target 80%)
- Error rate reduction: 22%
decision: Adopted pattern exceeds all targets
official_date: 2026-06-20
transition_note: Graduated from experimental to official decision
Trigger: Decision overturned or revoked by council
Who triggers: Council member or architect (council approval required)
Evidence required:
Dependent decisions:
Communication:
Example:
status: Cold
status_reason: revoked
revocation_authority: Architecture Council
revoked_date: 2026-07-01
revocation_reason: Security issue in third-party library
revocation_details: |
Library X (used in D42 approach) disclosed CVE with no patch available.
Council voted unanimously to revoke D42 pending resolution.
Until resolved: no new codebases should adopt D42 pattern.
Existing implementations must migrate to D89 by 2026-09-01.
affected_teams: [TeamA, TeamB, TeamC]
migration_deadline: 2026-09-01
replacement_decision: D89
council_letter: "[link to council decision document]"
Decision marked for demotion
↓
Is it time-based aging (6mo Active, 3mo Warm, 12mo Cold)?
├─ YES → Apply Rule 1 (automated, no approval)
└─ NO → Continue below
Is it being replaced by a newer decision?
├─ YES → Apply Rule 2 (team lead approval)
└─ NO → Continue below
Did the system context change (constraints, product, environment)?
├─ YES → Apply Rule 3 (domain expert approval + dependents flagged)
└─ NO → Continue below
Is this an experiment that concluded?
├─ YES → Apply Rule 4 (experiment owner approval)
└─ NO → Continue below
Was this decision formally revoked by council?
├─ YES → Apply Rule 5 (council authority + urgent migration)
└─ NO → Decision remains Active (no demotion rule triggered)
Evergreen decisions are foundational principles or patterns that stand the test of time and should never be archived. They represent organizational wisdom, core architecture principles, stable contracts, and validated lessons that transcend individual projects or time periods.
Definition: "This approach works for ALL projects and ALL contexts"
Characteristics:
How to identify:
How to mark:
status: Active
evergreen: true
evergreen_type: pattern
evergreen_since: 2024-01-15
pattern_scope: "All projects, all teams, all contexts"
Search and maintenance:
# Find all evergreen patterns
brain-read tag:* evergreen:true evergreen_type:pattern
# Periodic validation (annually)
Review all evergreen patterns to ensure still universal
Check for any new edge cases discovered
Update timestamp if revalidated
Examples:
Definition: "Core tenet of our architecture that defines who we are"
Characteristics:
How to identify:
How to mark:
status: Active
evergreen: true
evergreen_type: architecture
evergreen_since: 2022-06-01
architectural_principle: "Always prioritize customer data privacy over feature velocity"
enforcement: "All systems must implement end-to-end encryption by default"
Search and maintenance:
# Find all architecture principles
brain-read tag:* evergreen:true evergreen_type:architecture
# Annual architecture review
Review all architectural principles
Assess if new product directions require updates
Solicit feedback from senior engineers
Update guidance based on lessons from past year
Examples:
Definition: "Stable, long-lived interface that won't change"
Characteristics:
How to identify:
How to mark:
status: Active
evergreen: true
evergreen_type: contract
evergreen_since: 2023-03-15
contract_stability: "Breaking changes require 6-month deprecation period and council approval"
dependent_systems: [PaymentService, InventoryService, NotificationService]
versioning_strategy: "Additive changes only; removals require deprecation cycle"
Search and maintenance:
# Find all stable contracts
brain-read tag:api evergreen:true evergreen_type:contract
# Quarterly contract review
Audit all evergreen contracts for backward compatibility
Check for any dependent system failures or incompatibilities
Plan deprecation cycles for any necessary breaking changes
Communicate timeline to all dependent teams
Examples:
Definition: "Hard-won insight that shaped how we build systems; worth remembering forever"
Characteristics:
How to identify:
How to mark:
status: Active
evergreen: true
evergreen_type: lesson
evergreen_since: 2021-09-10
lesson_category: "Database selection rationale"
lesson_title: "Why we chose MySQL for financial transactions"
lesson_value: "Prevents pressure to switch databases in pursuit of cool tech"
Search and maintenance:
# Find all evergreen lessons
brain-read tag:* evergreen:true evergreen_type:lesson
# Lessons review (biannually)
Review all evergreen lessons for continued validity
Update context if new information discovered
Add new lessons from major learnings or incidents
Ensure lessons are accessible and discoverable
Examples:
Evergreen Lesson Example 1: Database Selection
id: D15
title: "Why MySQL for Financial Transactions"
status: Active
evergreen: true
evergreen_type: lesson
evergreen_since: 2021-09-10
## The Problem
Early on, we explored NoSQL for transaction logs. Benchmarks looked good.
Pressure from engineering to use trendy tech was high.
## What We Chose and Why
MySQL with InnoDB: Full ACID compliance, proven at scale, simple operations.
## The Lesson
Never optimize for engineering trendsiness when data integrity is on the line.
ACID guarantees prevented 47 data inconsistency bugs that would have been
invisible in eventual-consistency systems. Cost of fixing one incident: $300K+.
## Why This Remains Evergreen
The reasoning—data integrity > cool technology—transcends database choices.
Even if we eventually use different database, this principle remains.
Prevents repeating "why did we choose the cool tech" mistakes in future.
## When This Lesson Is Relevant
- Any discussion of changing financial transaction storage
- Tech selection for any critical business data
- Evaluating new databases or frameworks
- When pressure mounts to adopt trendy technology
## What NOT to Infer
This is NOT "never use NoSQL" (we use it for logs, caching, analytics).
This IS "think carefully about data integrity requirements first".
Evergreen Lesson Example 2: Team Scaling
id: D28
title: "Why Microservices Didn't Scale Our Org"
status: Active
evergreen: true
evergreen_type: lesson
evergreen_since: 2020-06-15
## The Problem
With 15 engineers, we split into microservices to "scale better".
Expected: independent team deployment, faster iteration.
Reality: coordination overhead, cross-service debugging nightmare, 12 months to stable.
## What We Learned
Microservices scale teams, not monoliths. We had one team with unclear boundaries.
Should have scaled team structure first, then services to match org structure.
## The Lesson
Organization structure determines system architecture, not vice versa.
Conway's Law: System design mirrors communication structure of org that built it.
Reverse-engineering architecture to make teams autonomous doesn't work.
## Why This Remains Evergreen
True regardless of tech stack or company size.
Valid at 5 people and 500 people.
Prevents repeating expensive architecture mistakes.
## When This Lesson Is Relevant
- Any architectural redesign proposal
- Decisions about microservices, modular monolith, or monolith
- Team restructuring discussions
- When teams request architectural changes to improve independence
When transitioning a decision to Cold or Archived status, capture:
age: Natural aging period reachedsuperseded_by: Explicit replacement (provide decision ID)outdated: No longer applicableexperimental_end: Experiment concludedrequest: Explicit archival requestThese pitfalls represent common mistakes in decision archival that undermine the brain's long-term value.
The mistake: Decision marked Archived with minimal context. Status changed, timestamp recorded, but lessons and reasoning lost.
Consequences:
Prevention:
Example (WRONG):
status: Archived
archived_date: 2027-01-15
# No context! Future team confused.
Example (RIGHT):
status: Archived
archived_date: 2027-01-15
archived_reason: "Time-based (24 months) + no dependents"
lessons_learned: |
What worked:
- Event-sourced audit trail was rock-solid, no data inconsistencies
- Debugging production issues easier with full event history
What didn't work:
- Event store grew to 50GB/year (unsustainable for small teams)
- Reconstruction queries slow on full history (analytical queries suffered)
- Operational complexity high (rebalancing partitions took days)
Why we changed:
D156 (incremental snapshots) provides 95% of benefits with 5% of cost.
Lessons from D42 informed design of D156.
When to revisit D42:
- If querying historical data becomes critical (archival/compliance)
- If operational costs justify engineering investment
- If we need unforgeable audit trail for regulatory reasons
The mistake: Decision remains marked Active years after becoming obsolete. No one updated status because no formal archival process existed.
Consequences:
Prevention:
Detection query:
# Find all Active decisions with no updates in past 18 months
brain-read status:active updated_before:2025-10-10
# Find Cold decisions older than 12 months (should consider archival)
brain-read status:cold age_cold_months>12
Example (WRONG - D42 still Active):
id: D42
title: "Graduated API Versioning"
status: Active # WRONG! Been superseded for 2+ years!
date_created: 2024-11-15
last_updated: 2024-11-20
Example (RIGHT - D42 properly demoted):
id: D42
title: "Graduated API Versioning"
status: Archived
date_created: 2024-11-15
last_updated: 2027-01-15 # When archived, not when created
demotion_timeline: |
2024-11-15: Active (created)
2025-05-15: Warm (6 months aging)
2025-08-15: Cold (superseded by D89)
2027-01-15: Archived (12+ months cold, no dependents)
The mistake: Decision marked as evergreen but then archived without escalating to council. Institutional wisdom lost, dependent decisions broken.
Consequences:
Prevention:
evergreen: true at decision creationevergreen: true without council overrideSafety gate implementation:
# System rule: Cannot archive evergreen decision
if status_change == "to Archived" and decision.evergreen == true:
REJECT with message: "Cannot archive evergreen decision.
Escalate to Architecture Council for review."
Example (WRONG - evergreen archived):
id: D15
title: "Why MySQL for Financial Transactions"
status: Archived # WRONG! This is evergreen!
evergreen: true # Conflicting tags!
# Decision lost, but archival happened anyway.
Example (RIGHT - evergreen protected):
id: D15
title: "Why MySQL for Financial Transactions"
status: Active # Protected, won't be archived
evergreen: true
evergreen_type: lesson
evergreen_since: 2021-09-10
archival_protection: "Cannot archive without council approval"
The mistake: Decision archived without documenting when/how it might be relevant again. If pattern resurfaces, decision is lost.
Consequences:
Prevention:
Recovery criteria checklist:
When documenting archival, answer:
[ ] What problem did this decision solve?
[ ] Under what system constraints was it valid?
[ ] What changed that made it invalid?
[ ] What would have to be true to make it valid again?
[ ] How would future team recognize this scenario?
Example (WRONG - no recovery path):
status: Archived
archived_date: 2027-01-15
reason: "Superseded by D89"
# No recovery criteria! If D89 fails, we're stuck.
Example (RIGHT - recovery documented):
status: Archived
archived_date: 2027-01-15
reason: "Superseded by D89"
recovery_criteria: |
D42 would be relevant again if:
- D89 (header-based versioning) proves unmaintainable (e.g., proxy incompatibilities)
- External mandate requires URL-based versioning for SEO or analytics
- Client ecosystem shifts back to prefer path-based versioning
- New product line has same constraints as 2024 when D42 was created
recovery_process: |
1. If recovery scenario triggered: contact architecture team
2. Retrieve D42 from archive + full lessons learned
3. Assess if context still matches (it should, or D42 won't be valid)
4. If match: unarchive, promote to Active
5. If no match: use D42 as inspiration for new decision
The mistake: Decision demoted (Active→Warm, Warm→Cold) without notifying affected teams. Teams unaware guidance has changed status.
Consequences:
Prevention:
Communication template:
Subject: NOTICE - Decision [ID] Status Change to [NEW_STATUS]
Team,
Decision [TITLE] status is being changed to [NEW_STATUS] effective [DATE].
What this means:
[Explain new status and implications]
Your action items:
- Review current usage of this decision
- If applicable, plan migration to successor decision
- Update internal documentation if you've built on this approach
Next steps:
- [NEW_STATUS] is expected to remain for [DURATION] before [NEXT_STATUS]
- Questions or concerns? Contact [DOMAIN_EXPERT]
Timeline:
[CREATED] → Active
[DATE1] → Warm (this change)
[DATE2] → Cold (expected)
[DATE3] → Archived (expected, unless circumstances change)
Successor decision:
If applicable, see [SUCCESSOR_ID] for recommended approach.
Demotion and archival work at scale when automated. Decision lifecycle automation prevents stale decisions and maintains system integrity.
Time-based automation (no human approval needed):
# Daily job: Check all Active decisions
for decision in decisions with status=Active:
if (now - decision.created_date) > 6 months:
decision.status = Warm
decision.status_since = now
decision.status_reason = age
notify_teams(decision.tags) # Informational only
# Weekly job: Check all Warm decisions
for decision in decisions with status=Warm:
if (now - decision.status_since) > 3 months:
decision.status = Cold
decision.status_since = now
decision.status_reason = age
notify_teams(decision.tags) # Recommend review
# Monthly job: Check all Cold decisions
for decision in decisions with status=Cold:
if (now - decision.status_since) > 12 months and not decision.evergreen:
decision.status = Archived
decision.archived_date = now
decision.archived_by = system
decision.archived_reason = age
log_archival(decision) # Audit trail
Event-based automation (requires human approval):
# User marks decision as superseded
if decision.status_change_request == superseded_by:
requires_approval: domain_expert
approval_gate: "Link to successor decision"
notification: teams_using_this_decision
# Domain expert approves validity demotion
if decision.status_change_request == outdated:
requires_approval: domain_expert + decision_stakeholder
approval_gate: "Evidence of changed context"
notification: dependent_decisions_flagged_for_review
# Council revokes decision
if decision.revocation_request:
requires_approval: council_vote
approval_gate: "Council decision log"
notification: urgent_to_all_dependents
migration_deadline: 30_days
Automated review (no approval required):
Manual review (approval required):
Approval workflow:
1. Decision owner initiates demotion request
2. System checks: can this be automated or requires approval?
3. If automated: execute immediately, notify teams
4. If manual: route to approver based on demotion type
5. Approver reviews: evidence provided? impact assessed? teams notified?
6. Approver decision: approve, request more info, or reject
7. If approved: execute status change, log decision, archive if needed
8. If rejected: return to decision owner with feedback
Notification matrix:
| Status Change | Who's Notified | Message Type | Urgency |
|---|---|---|---|
| Active→Warm | Teams with tag | "Your decision is entering maintenance mode" | Low |
| Warm→Cold | Teams with tag | "Recommend reviewing this decision and its successors" | Medium |
| Cold→Archived | Teams with tag + dependents | "This decision is moving to archive; no impact if you've migrated" | Low |
| Supersession | Direct dependents | "Your decision has been superseded; plan migration" | Medium |
| Validity change | Dependent decisions | "Context changed; review this decision's validity" | High |
| Experimental end | Experiment participants | "Results analyzed; decision on adoption/rejection" | High |
| Governance revoked | All dependents | "Council has revoked this decision; urgent migration required" | Critical |
Notification content rules:
Track demotion pipeline health:
# Weekly dashboard
- Active decisions: [count]
- Warm decisions: [count]
- Cold decisions: [count]
- Archived decisions: [count]
- Evergreen decisions: [count]
# Demotion velocity
- Decisions demoted this week: [count]
- Decisions archived this month: [count]
- Average decision lifecycle: [duration]
- Decisions with no dependents (ready for archival): [count]
# Health metrics
- Decisions with complete lessons learned: [%]
- Decisions with recovery criteria documented: [%]
- Decisions with no updates in 18+ months: [count] (action needed?)
- Evergreen decisions audited in past 12 months: [%]
# Archival effectiveness
- Decisions recovered from archive (last 12 months): [count]
- Recovery rate (archived that became active again): [%]
- False positives (decisions should have stayed active): [count]
Red flags that indicate process breakdown:
Architecture Council's role in lifecycle management:
Quarterly evergreen audit: Review all evergreen: true decisions
Monthly archival review: Approve archival of decisions ready for archive
Incident response: When decision revocation needed
Annual brain health: Full decision landscape audit
include_cold=true includes Cold decisionsinclude_archived=true includes Archived decisionsinclude_all=true includes all statusessearch status:active # Only currently relevant decisions
search status:warm # Aging decisions, still in use
search status:cold # Deprecated decisions
search status:archived # Historical archive
search status:"cold|archived" # Historical research
search status:"*" # All decisions (all statuses)
search tag:api-versioning status:coldtag:cache-strategy status:* shows cache decisions across timeArchival is not destruction. The brain maintains full auditability of all decisions, even archived ones. Recovery processes restore archived decisions when their patterns become relevant again.
Automated identification:
evergreen: trueManual identification:
Decision classification:
# Example candidates report
archival_candidates:
- id: D42
title: "Graduated API Versioning"
status: Cold
age_cold: 14 months
dependent_count: 0
last_referenced: 2026-08-15
candidate_reason: "Superseded by D89, no dependents, not referenced in 9 months"
evergreen: false
recommendation: SAFE_TO_ARCHIVE
- id: D15
title: "MySQL for Financial Transactions"
status: Cold
age_cold: 2 years
dependent_count: 12
last_referenced: 2026-10-10
candidate_reason: "Actively referenced in architecture decisions"
evergreen: false
recommendation: KEEP_ACTIVE # Still provides architectural wisdom
Who reviews: Domain expert + stakeholders from dependent teams (if any)
Review questions:
Approval workflow:
Review checklist:
[ ] Decision is genuinely outdated (not just superseded)
[ ] No active dependents (or dependents have migrated)
[ ] Lessons learned section is complete
[ ] Context preserved for potential future recovery
[ ] Not marked as evergreen (double-checked)
[ ] Dependent teams (if any) notified and approved
[ ] Archival reason clearly documented
[ ] Recovery criteria documented (if relevant)
Update decision record:
status: Archived
archived_date: 2026-11-15
archived_by: eng-lead-team@company.com
archived_reason: "Time-based (24 months total) + no active dependents"
archival_context: |
D42 documented the API versioning approach for 2023-2026.
Superseded by D89 (header-based versioning) as of Dec 2025.
Last dependent migrated off in Aug 2026.
No new codebases expected to reference this decision.
recovery_scenarios: |
Could revisit if:
- New product line requires backward-compatible API versioning
- Client ecosystem strongly prefers path-based versioning
- Regulatory requirements need URL-based API versioning (audit trail)
lessons_preserved: |
- Path-based versioning: works for 6+ months
- Client migration slower than expected (assume 18mo, not 12mo)
- URL pollution problem: each version doubles URL surface area
- Deprecation strategy: must communicate timeline clearly
- See D89 for lessons from header-based approach
System actions:
include_archived=true)Who to notify:
What to communicate:
Communication template:
Subject: Decision D42 Archived - "Graduated API Versioning"
Team,
Decision D42 has been archived effective 2026-11-15 as a result of:
- 24-month lifecycle completion (decision made 2024-11-15)
- Supersession by D89 "Header-Based API Versioning" (adopted Dec 2025)
- No active dependents (last migration completed Aug 2026)
Why archived:
The graduated API versioning approach has been proven and documented.
Newer approach (D89) provides benefits of path-based clarity with reduced
URL pollution. Moving to archive makes room in "active decisions" for
new guidance without losing historical context.
What you should do:
- If currently using D42 approach: migrate to D89 (see migration guide)
- If decision references D42: update reference to point to D89
- No action needed if you've already migrated
Recovery possibility:
Archived decisions can be unarchived if circumstances change. Contact
architecture team if you have use case that requires D42 approach.
Questions? See D42 "Lessons Learned" section or contact eng-lead@company.com
Best,
Architecture Team
Recovery happens when an archived decision becomes relevant again. Three recovery paths exist:
When: Exact circumstances match archived decision pattern Process:
Example:
Decision: D42 "Graduated API Versioning"
Original: Archived 2026-11-15
Reactivation: 2027-03-10
Reason for recovery: New product platform needs API versioning.
Architecture matches original D42 constraints: greenfield system,
external clients, need to deprecate versions gradually.
Decision: REACTIVATE D42 (same approach, proven to work)
Updated record:
status: Active (reactivated)
reactivated_date: 2027-03-10
reactivated_from: Archived
reactivation_reason: "New product platform matches original D42 constraints"
prior_context: "See archived metadata for lessons from 2023-2026 implementation"
cross_reference: "See D89 for alternative approach (header-based)"
When: Some aspects of archived decision remain valid, but not all Process:
Example:
Decision: D125 "Modified Graduated API Versioning"
Inspired by: D42 (archived)
Date: 2027-03-10
Context:
D42 documented graduated API versioning with 12-month deprecation window.
For new platform, constraints changed: smaller client base, shorter product cycle.
What we're adopting from D42:
- Graduated deprecation strategy (keep multiple versions in parallel)
- Deprecation timeline communication (clear deadline for migration)
What we're changing from D42:
- Timeline: 6 months deprecation (vs 12 months in D42)
- Versioning: header-based (vs URL path in D42, see D89)
- Client population: internal-only (vs external in D42)
Why not just reactivate D42:
Different constraints make D42 timeline too long and approach too heavy.
D42 was valuable for learning; adapting lessons to new context.
When: Decision is obsolete as guidance, but lessons are valuable Process:
Example:
Decision: D126 "Why Graduated Deprecation Works"
Lesson from: D42 (archived), D89 (active)
Date: 2027-03-10
Thesis:
Graduated deprecation—keeping multiple versions in parallel and
phasing out old versions over time—is robust pattern across APIs,
frameworks, and product designs.
Evidence from our experience:
- D42 (2024): Tried graduated deprecation with URL-based API versioning
Result: Worked, but slower adoption than expected
Timeline: 18 months (not 12), high operational cost
- D89 (2025): Adopted graduated deprecation with header versioning
Result: Faster adoption, lower operational cost
Timeline: 12 months achieved, good client compliance
Lessons:
1. Graduated deprecation is robust across different versioning approaches
2. Timeline depends on client population (internal vs external)
3. Clear deprecation communication is essential
4. Total operational cost includes backward compatibility, not just timeline
When to apply:
Any API or interface with external consumers who can't upgrade instantly.
Best for platforms with heterogeneous client base.
When NOT to apply:
Internal-only APIs (hard cutover better); clients already distributed
(rolling deployment better); small client base (negotiate directly).
Reference decisions:
- D42: Original approach with URL-based versioning (Archived)
- D89: Current approach with header-based versioning (Active)
When an archived pattern becomes relevant again:
Decision: D42 "Graduated API versioning"
Original: Archived 2027-03-15
Reactivation: 2027-06-10
Reason: New product line needs API versioning, same constraints as original.
Previous lessons show graduated deprecation works despite slow client migration.
Will apply same approach with updated timeline based on D42 experience.
Cross-reference: See D42 for historical context and lessons learned.
---
id: D42
title: Graduated API Versioning Strategy
status: Active
date: 2026-03-15
---
API versioning via URL path (/v1/, /v2/, etc.).
Clients must migrate within 12 months of deprecation notice.
Status: Active (newly decided)
status: Warm
status_since: 2026-09-15
status_reason: age
notes: 6 months of active use, still in production
status: Cold
status_since: 2026-12-15
status_reason: superseded_by
successor: D89
successor_title: Header-Based API Versioning
lessons: |
- Graduated deprecation worked well for first 6 months
- Client migration slower than expected (12 months wasn't enough)
- For v2: use header versioning instead (less cognitive load)
- Key insight: path-based versioning creates URL pollution
status: Archived
status_since: 2027-03-15
status_reason: age
cold_duration: 1 year
archived_context: Historical reference for API versioning evolution
reactivation_criteria: |
Could revisit if:
- New product line with similar constraints as D42
- Client ecosystem strongly prefers URL-based versioning
brain-read tag:api-versioning status:* include_all=true
Results: D42 (Archived), D89 (Active)
Insight: Evolved from path-based to header-based over 3 years
Timeline: D42 → (6mo) Warm → (6mo) Cold → (1y) Archived; D89 in use
Symptom: Attempt to archive decision, but other active decisions still reference it as parent or prerequisite.
Do NOT: Archive if dependents are still active. Do NOT orphan child decisions.
Mitigation:
grep -r "parent_decision: D<id>\|depends.*D<id>" ~/forge/brain --include="*.md"Escalation: NEEDS_COORDINATION — Decision has active dependents. Cannot archive without updating them first. Notify dependent teams to migrate to successor decision or update parent references.
Symptom: Pattern that was archived resurfaces; new context makes archived approach relevant again.
Do NOT: Create duplicate decision with same content. Do NOT ignore archived decision.
Mitigation:
grep -r "keyword" ~/forge/brain/archive --include="*.md"status: archived → status: warm or status: activereactivated_date: <date>, reactivation_reason: "Pattern needed again due to <context>"decision: reactivate D<id> <title> — pattern relevant again for <new-context>Escalation: NEEDS_CONTEXT — Archived decision pattern needed again. Verify context has truly changed (not just forgotten). If reactivating, update dependent decisions and document why archived decision is now valid.
Symptom: Decision marked Archived with no explanation of why (missing archived_reason, lessons_learned).
Do NOT: Archive without documenting reason. Do NOT create undocumented archival.
Mitigation:
status_reason: age, superseded_by, outdated, experimental_end, revokedlessons_learned: what worked, what didn't, what we'd do differentlyreactivation_criteria: when would we reconsider this approach?Escalation: NEEDS_INFRA_CHANGE — If discovered during audit, add retroactive documentation with commit message explaining why decision was archived and what lessons were learned.
Symptom: Decision being archived but multiple successors exist (no single D replaces it).
Do NOT: Pick arbitrary replacement. Do NOT leave ambiguous.
Mitigation:
grep -r "parent: D<id>\|related.*D<id>" ~/forge/brain --include="*.md" | grep -v archivedsuccessor_decision_1: D<id1> — use this for scenario Asuccessor_decision_2: D<id2> — use this for scenario BEscalation: NEEDS_COORDINATION — Multiple successors for one decision. Coordinate with teams using original decision to determine which successor applies to their context. May require creating new decision that synthesizes approaches.
Symptom: Attempt to move Active → Archived without passing through Warm and Cold stages.
Do NOT: Skip lifecycle stages. Do NOT archive without giving teams transition time.
Mitigation:
Escalation: NEEDS_CONTEXT — Direct archival skipped lifecycle safeguards. Revert to Warm status and follow proper demotion timeline, OR escalate to council for emergency revocation approval if revocation reason is valid.
Decision marked for removal
↓
Should this decision be permanently deleted from history?
├─ YES → STOP. Decisions are never deleted. Demote to archived instead.
└─ NO → Continue below
Has the decision aged naturally (6mo Active, 3mo Warm, 12mo Cold)?
├─ YES → Apply Rule 1 (Time-Based): Demote to Archived
└─ NO → Continue below
Is there a successor decision that replaces it?
├─ YES → Apply Rule 2 (Supersession): Mark `successor: D<id>`, demote through Warm→Cold→Archived
└─ NO → Continue below
Did the system context change (constraints, product direction, regulation)?
├─ YES → Apply Rule 3 (Validity): Document what changed, demote through Warm→Cold
└─ NO → Continue below
Was this an experiment that concluded?
├─ YES → Apply Rule 4 (Experimental): Document results, demote through Warm→Cold
└─ NO → Continue below
Was this decision formally revoked by council (security, policy)?
├─ YES → Apply Rule 5 (Governance): Urgent notification, may skip to Archived if critical
└─ NO → Decision remains Active (no demotion rule triggered)
Result:
- Default lifecycle: Active → Warm (6mo) → Cold (3mo) → Archived (12mo)
- With successor: mark supersession, follow lifecycle
- With broken context: mark outdated, follow lifecycle
- With experimental conclusion: mark experimental_end, follow lifecycle
- With council revocation: can skip Warm/Cold if critical (security), escalate for approval
- Never delete: always demote, always document reason, always preserve audit trail
Related Skills: brain-read, brain-write, brain-remember
git -C ~/forge/brain commit, and git log --oneline -1 shows the commit[P*-BRAIN-FORGET] log line appears in the conductor transcript before claiming the demotion completeBefore claiming completion:
lessons_learned and status_reason fields are populated in the decision filesuccessor: fieldbrain-read: Fetches the current decision file before demotion; brain-forget requires reading the file to confirm status.brain-write: Creates the decision record that brain-forget later archives; successor decisions are recorded via brain-write.brain-recall: Search before forget — confirm no active decision depends on the one being demoted.brain-why: Trace provenance before archiving; use brain-why to identify downstream decisions that reference the one being forgotten.brain-link: Checks and updates successor: and related: edges when a decision is archived.