メニュー
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.
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: A decision is being superseded, deprecated, or has aged out. Archive it without deletion — marks as warm→cold→archived with full audit trail.
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-link |
| description | 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. |
| type | flexible |
| requires | ["brain-read"] |
| version | 1.0.0 |
| preamble-tier | 2 |
| triggers | ["link brain files","cross-reference decisions","connect brain entries"] |
| allowed-tools | ["Bash","Write"] |
CRITICAL: Read this section before creating any link. These anti-patterns corrupt the decision graph.
Why it fails: Star topology with single hub creates fake dependency chains, obscures real influence patterns, makes graph traversal meaningless.
Enforcement — MUST:
Why it fails: Using only related destroys graph's traversal value. replaces/conflicts/complements/variant enable different query paths. A brain-recall query for "all decisions that replaced D42" returns nothing if you used related.
Enforcement — MUST:
replaces for supersession chains (enables evolution queries)conflicts for mutually-exclusive choices (enables consistency analysis)complements for decisions that form a system (enables cohesion queries)variant for pattern instances across products (enables cross-product queries)Why it fails: Retroactive links lack provenance. When was relationship known? Who made decision knowing about the other? Retroactive links are reconstructions, not records.
Enforcement — MUST:
Why it fails: Without explicit links, brain-recall and brain-why cannot traverse the graph. Inferences don't persist. Future searchers see isolated decisions, not patterns.
Enforcement — MUST:
Why it fails: replaces is directional. D005 replaces D002 ≠ D002 replaces D005. Incorrect direction corrupts supersession queries.
Enforcement — MUST:
depends-on D17, also create D17 required-by D42)replaces is correct; bidirectional conflicts is correct; variant should be directional (global → instance)If you are thinking any of the above, you are about to violate this skill.
EVERY SEMANTIC EDGE MUST INCLUDE A DECLARED LINK TYPE, DIRECTIONALITY, AND PROVENANCE (WHEN IT WAS CREATED AND WHY). A LINK WITHOUT THESE THREE ELEMENTS IS NOT A LINK — IT IS NOISE THAT CORRUPTS THE DECISION GRAPH.
If you notice any of these, STOP and do not proceed:
link_type — An untyped link is ambiguous: "related" means nothing specific when querying "what does D42 supersede?" or "what contradicts D42?". STOP. Every link must specify its type: supersedes, depends-on, contradicts, implements, extends, or informs.depends-on D17, D17 must also have a required-by link pointing to D42.brain-read to verify both source and target decision IDs exist before creating any link.supersedes link is created without marking the superseded decision's status — A supersedes link without a status update leaves the old decision appearing active. STOP. When creating a supersedes link, also update the superseded decision's status to superseded via brain-forget or brain-write.D42), never to product slugs or repo names.Link decisions across products, projects, and time. Create a queryable graph of decision relationships, patterns, and evolution.
The brain-link skill enables semantic connections between decisions, allowing you to:
Built on top of brain-read, which provides decision metadata and history.
Define how decisions relate to each other:
Decisions that influenced each other without formal ordering.
D40: REST design principles
--related--> D41: Error handling strategy
--related--> D42: Graduated API versioning
Use when decisions share context or emerged together.
Newer decision supersedes older decision. Tracks decision evolution.
D42: Graduated API versioning (2022-06)
--replaces--> D89: Header-based versioning (2023-02)
--replaces--> D127: Content-negotiation versioning (2024-01)
Use when a better approach emerges or constraints change.
Mutually exclusive choices. Cannot both be true in same system.
D30: Cache-aside strategy
--conflicts--> D31: Write-through caching
--conflicts--> D32: Write-behind caching
Use when decisions represent alternative designs.
Works together as a system. Neither sufficient alone.
D42: Graduated API versioning
--complements--> D46: Error code taxonomy
--complements--> D47: Deprecation timeline strategy
Use when decisions form a cohesive whole.
Same pattern applied in different products/contexts. Allows "show all instances".
D42: Graduated API versioning (global decision)
--variant--> D43 (shopapp instance)
--variant--> D44 (production instance)
--variant--> D45 (mobile instance)
Use when same pattern instantiated differently across products.
Tags enable cross-cutting queries and pattern discovery.
Abstract ideas and principles:
#api-versioning — API evolution strategy#eventual-consistency — Consistency model#cache-invalidation — Cache freshness#rate-limiting — Traffic control#observability — Monitoring and tracing#resilience — Fault tolerance#idempotency — Repeated operation safetyProven design patterns:
#circuit-breaker — Fault isolation#bulkhead — Resource isolation#saga — Distributed transaction#bloom-filter — Set membership#backpressure — Flow control#exponential-backoff — Retry strategy#gossip — Peer-to-peer syncBusiness/feature areas:
#auth — Authentication & authorization#payments — Payment processing#search — Search functionality#notifications — Messaging system#inventory — Stock management#catalog — Product data#recommendations — ML-based suggestionsSystem design dimensions:
#async — Asynchronous pattern#sync — Synchronous pattern#hybrid — Mixed sync/async#event-driven — Event-based architecture#request-reply — RPC-style communication#publish-subscribe — Pub/sub messaging#database — Data persistence#cache — In-memory storageDecision properties:
#breaking-change — Client-incompatible#deprecation — Phased retirement#rollback-plan — Can unwind if needed#tech-debt — Known limitation#performance-critical — SLO-impacting#security-critical — Security-relevantLink same decisions across product instances to enable cross-product queries.
Products in the system:
shopapp — Customer shopping appproduction — Admin/operations dashboardmobile — Native mobile appfuture-product — Planned productGlobal decision → Product instances:
D42: Graduated API versioning (global, 2022-06)
--variant--> D43 (shopapp, 2022-07)
Product: shopapp
Status: stable
Notes: v1, v2, v3 endpoints active
--variant--> D44 (production, 2022-08)
Product: production
Status: stable
Notes: v1, v2 active; v0 deprecated
--variant--> D45 (mobile, 2023-01)
Product: mobile
Status: stable
Notes: v1 only (reduced API surface)
Track how decisions evolve and change over time.
Show progression from original to current:
D42: Graduated API versioning (2022-06, REST endpoints)
Status: stable
Details: /v1/users, /v2/products, etc.
--replaces--> D89: Header-based versioning (2023-02)
Trigger: Reduced URL clutter, easier load balancing
Details: X-API-Version: 2 header
Status: stable
--replaces--> D127: Content-negotiation versioning (2024-01)
Trigger: GraphQL adoption, unified versioning strategy
Details: Accept: application/vnd.api+json;version=2
Status: current
Include in each link:
Standard query syntax for decision graph traversal.
By Decision ID:
show decisions linked to D42
show D42 variants
show D42 successors
show D42 predecessors
By Tag:
show all decisions tagged #api-versioning
show decisions tagged #api-versioning AND #breaking-change
show decisions tagged (#circuit-breaker OR #bulkhead)
By Product:
show all decisions on product=shopapp
show decisions on product=shopapp AND tag=#async
show product=shopapp AND status=current
By Domain:
show decisions on domain=auth
show decisions on domain=auth AND tag=#resilience
Evolution Tracking:
show evolution chain: D42 → current
show all replacements: D42 → D89 → D127 → ?
show change history: D42 (when/why/impact)
Cross-Product Patterns:
show all products using #api-versioning
show product=shopapp using pattern=#circuit-breaker
show decisions varying by product (D42 variants)
Graph Traversal:
show neighbors: D42 (depth=1)
show closure: D42 (depth=2)
show related-decisions: tag=#eventual-consistency (depth=all)
Aggregations:
count decisions by tag
count decisions by product
count decisions by status
show decisions created in Q2-2023
{
id: "D42",
title: "Graduated API versioning",
created: "2022-06-15",
product: ["shopapp", "production"],
domain: "api",
tags: ["#api-versioning", "#sync", "#breaking-change"],
status: "stable" | "current" | "deprecated" | "retired",
summary: "Support multiple API versions via URL path (/v1, /v2)",
details: { ... },
link_refs: ["D40", "D41", "D89"]
}
{
from: "D42",
to: "D89",
type: "replaces",
when: "2023-02-20",
why: "Reduce URL clutter, improve load balancing",
status: "stable",
impact: {
products: ["shopapp", "production"],
breaking: true,
migration_timeline: "6 months"
}
}
{
tag: "#api-versioning",
decisions: ["D40", "D42", "D43", "D44", "D45", "D89", "D127"],
count: 7,
products: ["shopapp", "production", "mobile"],
domains: ["api"]
}
Complete decision graph showing all relationship types:
D40: REST design principles (2022-04)
tags: #sync, #api
├─→ (complements) D41: Error handling strategy
│ └─→ (variant) D41a (shopapp), D41b (production)
│
└─→ (complements) D42: Graduated API versioning
tags: #api-versioning, #sync, #breaking-change
├─→ (variant) D43 (shopapp, 2022-07)
│ tags: product=shopapp
│ ├─→ (complements) D46: Error code taxonomy
│ │ tags: #error-handling, #api
│ │ ├─→ (variant) D46a (shopapp), D46b (production)
│ │ └─→ (related) D47: Deprecation timeline
│ │
│ └─→ (replaces) D89: Header-based versioning (2023-02)
│ tags: #api-versioning, #sync
│ migration_timeline: "6 months"
│ ├─→ (variant) D89a (shopapp), D89b (production)
│ └─→ (replaces) D127: Content-negotiation (2024-01)
│ tags: #api-versioning, #async-ready
│ status: current
│
├─→ (variant) D44 (production, 2022-08)
│ tags: product=production
│ └─→ (complements) D46: Error code taxonomy
│
└─→ (variant) D45 (mobile, 2023-01)
tags: product=mobile, #mobile
D30: Cache-aside strategy (2021-11)
tags: #cache, #eventual-consistency
├─→ (conflicts) D31: Write-through caching
├─→ (conflicts) D32: Write-behind caching
├─→ (complements) D20: Cache invalidation
│ tags: #eventual-consistency, #cache-invalidation
│ └─→ (related) D70: Search freshness SLO
│ tags: #search, #eventual-consistency
│
└─→ (variant) D30a (shopapp), D30b (production)
D50: Kafka for events (2023-06)
tags: #event-driven, #async, #resilience
├─→ (complements) D51: Dead-letter queue strategy
│ tags: #error-handling, #resilience
├─→ (complements) D52: Event versioning
│ tags: #api-versioning, #event-driven
│ └─→ (replaces) D100: Header-based event versioning
│
└─→ (variant) D50a (shopapp), D50b (production)
Tag: #api-versioning
Decisions: D40, D42, D43, D44, D45, D46, D89, D127, D52
Concepts: API evolution, backward compatibility
Products: shopapp, production, mobile
Tag: #eventual-consistency
Decisions: D20, D30, D30a, D30b, D70
Concepts: Consistency model, cache freshness
Domains: search, notifications
Product: shopapp
Decisions: D1-D100 (full product topology)
Tags: #api-versioning, #async, #cache, #resilience
Status: production
brain-link: query tag=#api-versioning
Results:
├─ D40: REST design principles (2022-04) [related decisions]
├─ D42: Graduated API versioning (2022-06) [anchor]
│ ├─ D43 (shopapp variant, 2022-07)
│ ├─ D44 (production variant, 2022-08)
│ ├─ D45 (mobile variant, 2023-01)
│ ├─ D46: Error code taxonomy (complements)
│ ├─ D47: Deprecation timeline (related)
│ └─ D89: Header-based versioning (replaces, 2023-02)
│ └─ D127: Content-negotiation (replaces, 2024-01) [current]
├─ D52: Event versioning (2023-08)
│ └─ D100: Header-based event versioning (replaces)
└─ (7 total decisions)
Insights:
- Evolution: URL → Headers → Content-negotiation
- Pattern adopted across 3 products
- 2 generations, 1 current approach
- Related: error handling, deprecation, domain-based strategy
brain-link: show D42 closure (depth=all)
Results:
Direct links (depth=1):
← D40: REST design (related)
← D41: Error handling (related)
→ D43, D44, D45 (variants)
→ D46: Error codes (complements)
→ D47: Deprecation (related)
→ D89: Header versioning (replaces)
Transitive links (depth=2):
→ D46 → D46a, D46b (variants)
→ D47 → D48: Sunset strategy (related)
→ D89 → D89a, D89b (variants)
→ D89 → D127: Content-negotiation (replaces)
Full closure: [D40, D41, D42, D43, D44, D45, D46, D46a, D46b,
D47, D48, D89, D89a, D89b, D127]
(15 decisions in full closure)
brain-link: evolution D42
Timeline:
┌─────────────────────────────────────────────────────┐
│ D42: Graduated API versioning (2022-06) │
│ Pattern: URL path versioning (/v1, /v2) │
│ Status: stable, active in shopapp, production │
│ Products: shopapp, production, mobile │
└─────────────────────────────────────────────────────┘
↓ (replaces)
Why: Reduce URL clutter, simpler
When: 2023-02
Migration: 6 months
┌─────────────────────────────────────────────────────┐
│ D89: Header-based versioning (2023-02) │
│ Pattern: X-API-Version header │
│ Status: stable, active in shopapp, production │
│ Benefits: Cleaner URLs, better load balancing │
└─────────────────────────────────────────────────────┘
↓ (replaces)
Why: Unified strategy for GraphQL
When: 2024-01
Migration: 3 months
┌─────────────────────────────────────────────────────┐
│ D127: Content-negotiation versioning (2024-01) │
│ Pattern: Accept header (application/vnd.api+...) │
│ Status: current │
│ Benefits: GraphQL + REST unified, W3C standard │
└─────────────────────────────────────────────────────┘
Change drivers:
- Load balancing constraints → headers
- GraphQL adoption → content negotiation
- Operational simplification → unified strategy
brain-link: query product=shopapp tag=#async
Results:
├─ D50: Kafka for events (2023-06)
│ ├─ D50a (shopapp variant)
│ └─ D51: Dead-letter queue strategy (complements)
├─ D70: Search freshness SLO (2023-09)
│ └─ D71: Search async indexing (relates)
└─ D85: Background job processing (2024-02)
└─ D86: Retries + exponential backoff (complements)
(3 decisions)
Insights:
- All async decisions involve event/messaging
- All include resilience/error handling complements
- Timeline: 2023-2024, recent additions
Use brain-link alongside brain-read:
1. brain-read: Look up decision D42
2. brain-link: Query "show D42 closure"
3. brain-read: Load each linked decision for full context
4. brain-link: Query evolution chain
5. brain-read: Load specific variants by product
The two skills are complementary:
Symptom: D001 complements D002, D002 replaces D001, creating a cycle.
Do NOT: Silently accept the cycle. Circular dependencies in a decision graph indicate unresolved conflicts or miscategorized relationships.
Action:
Escalation: NEEDS_CONTEXT
Symptom: D003 replaces D001 AND D007 replaces D001 (parallel supersession).
Do NOT: Treat as invalid — this is valid in parallel supersession scenarios (e.g., different products adopt different successors).
Action:
superseded (not deprecated)succeeded_by: [D003, D007]replaces: D001 link explicitlyEscalation: NEEDS_COORDINATION
Symptom: brain-link create D042 replaces D099 but D099.md doesn't exist in the brain.
Do NOT: Create dangling link pointing to non-existent decision.
Action:
replaces: D099 [ARCHIVED]Escalation: NEEDS_CONTEXT
Symptom: D010 conflicts D015, both status=active, both in production across multiple products.
Do NOT: Silently coexist. Active conflicting decisions indicate unresolved architectural choice.
Action:
applies_to: {D010: [product_a, product_b], D015: [product_c, product_d]}Escalation: NEEDS_COORDINATION
Symptom: brain-link query tag=#api-versioning depth=all returns partial results after 5-second timeout on brain with >500 decisions.
Do NOT: Use partial results for analysis. Partial graph closure gives false negatives.
Action:
tag=#api-versioning AND product=shopapp (returns in <1s)"depth=2 instead of depth=all (returns immediate neighbors)"Escalation: NEEDS_CONTEXT
START: You need to link two decisions
├─ Are these decisions equivalent across products/contexts?
│ ├─ YES → Use VARIANT
│ │ (D42 global → D43 shopapp instance)
│ │ Direction: global → instance
│ │ Query: "Show all instances of D42"
│ │
│ └─ NO → Continue
├─ Does one decision replace/supersede the other?
│ ├─ YES → Use REPLACES
│ │ (D42 v1 → D89 v2)
│ │ Direction: old → new (required)
│ │ Query: "Evolution chain: D42 → current"
│ │ Also mark old as status=deprecated/superseded
│ │
│ └─ NO → Continue
├─ Are these decisions mutually exclusive?
│ ├─ YES → Use CONFLICTS
│ │ (cache-aside vs write-through)
│ │ Direction: bidirectional (both directions okay)
│ │ Query: "Alternatives to D30"
│ │ Note: Both active only if they apply to different products
│ │
│ └─ NO → Continue
├─ Do these decisions work together to form a system?
│ ├─ YES → Use COMPLEMENTS
│ │ (API versioning + deprecation strategy)
│ │ Direction: bidirectional (both directions okay)
│ │ Query: "What goes with D42?"
│ │ Note: Neither sufficient alone
│ │
│ └─ NO → Continue
└─ Do these decisions share context but no formal relationship?
└─ YES → Use RELATED
(REST principles ← → Error handling)
Direction: bidirectional (both directions okay)
Query: "Related to D40"
Note: Weakest link type; use sparingly
END: Link created with correct type
START: You've chosen a link type. Create forward or reverse link too?
├─ Link type is REPLACES?
│ ├─ YES → DIRECTIONAL ONLY
│ │ Create: D42 --replaces--> D89
│ │ Do NOT create: D89 --replaces--> D42
│ │ Reason: Direction matters for evolution queries
│ │ Test: "Show what replaced D42" should find D89, not vice versa
│ │
│ └─ NO → Continue
├─ Link type is VARIANT?
│ ├─ YES → DIRECTIONAL ONLY
│ │ Create: D42_global --variant--> D43_shopapp
│ │ Direction: abstract/global → concrete/instance
│ │ Do NOT reverse (instance → global doesn't make sense)
│ │ Test: "Show instances of D42" finds D43, D44, D45
│ │
│ └─ NO → Continue
├─ Link type is CONFLICTS?
│ ├─ YES → BIDIRECTIONAL
│ │ Create: D30 <--conflicts--> D31
│ │ Reason: Conflict is symmetric
│ │ Test: "What conflicts with D30" finds D31, and vice versa
│ │
│ └─ NO → Continue
├─ Link type is COMPLEMENTS?
│ ├─ YES → BIDIRECTIONAL
│ │ Create: D42 <--complements--> D46
│ │ Reason: Complementary relationship is mutual
│ │ Test: "What goes with D42" finds D46, and vice versa
│ │
│ └─ NO → Continue
└─ Link type is RELATED?
└─ YES → BIDIRECTIONAL
Create: D40 <--related--> D41
Reason: Related is symmetric
Test: "Related to D40" finds D41, and vice versa
END: Link created with correct directionality
Verify: Can you traverse from both directions?
Future enhancements:
cat or Readgrep -r "^decision_id: <target-id>" ~/forge/brain --include="*.md" returning a resultgit -C ~/forge/brain log --oneline -1 -- <path>replaces/variant directional links, the reverse link was also created and verified to existreplaces, conflicts, complements, variant, or related) — not left untyped or defaulting to a catch-allbrain-write: Create decisions that brain-link will connect
brain-write, immediately use brain-link to connect it to related decisionsbrain-why: Trace provenance of any decision
brain-why to trace link creation, revision history, and rationalebrain-recall: Search for patterns in the decision graph
brain-recall provides full-text search; brain-link provides graph traversal#api-versioning, then use brain-link to find evolution chainbrain-forget: Archive deprecated decisions
brain-link to create the replaces link, then brain-forget to archive the old decisionstatus=superseded before archival to preserve provenance in the graphUsage Flow:
1. brain-write: Create new decision D100
2. brain-link: Link D100 to related decisions (D42, D89, etc.)
3. brain-recall: Query to find all related decisions and verify links
4. brain-why: Trace decision history and link provenance
5. brain-forget: Archive old decisions after marking with replaces link
Bidirectional Link: A link that travels in both directions. Used for CONFLICTS, COMPLEMENTS, RELATED. Query "What conflicts with D30?" finds D31 and vice versa.
Circular Dependency: A cycle in the link graph (D1 → D2 → D1). Invalid in decision graphs; indicates unresolved conflicts or miscategorization.
Closure (graph closure): The set of all reachable decisions from a starting decision, following all link types up to a specified depth.
Decision Node: A single decision (D42) with metadata: ID, title, creation date, product, domain, tags, status, summary.
Directional Link: A link with a source and target that are not interchangeable. Used for REPLACES and VARIANT. "D42 replaces D89" ≠ "D89 replaces D42".
Provenance: The history of when and why a link was created. Essential for understanding decision rationale.
Supersession: When one decision replaces another. Created with replaces link. Old decision marked status=superseded.
Variant: An instance of a pattern applied in a different product or context. Created with variant link. Used for cross-product queries.
Before claiming completion:
link_type — never left as untyped or defaulting to "related"replaces and variant are directional; conflicts, complements, related are bidirectional (reverse link created)when it was created and why the relationship existssupersedes link was created, the superseded decision's status was updated to superseded via brain-forget or brain-write