Bridge

Bridge — Cross-Project Connection Capture

Capture cross-project bridges in the moment, while you're in context. Bridges are knowledge — they live in a bridges directory, not in project artifacts.

Why

Bridges are discovered during work, not during planning. When you're deep in a meeting and realize "this pattern connects to another project" — that's when bridge captures it.

Step 0: Load Config

Read the project config file (path configured via $PRAXIS_DIR or equivalent). This file contains:

• Project aliases (keys), names, roles, tiers, goals, flywheel roles
• Stakeholders with also_in cross-references (for people-bridge detection)
• GTD and praxis paths

Use project YAML keys as aliases (case-insensitive matching). If a user types a project name instead of alias, fuzzy-match against name fields.

If config missing → ⚠️ No project config found. Create it with your project definitions.

Archetypes

Every bridge has a type. The 10 archetypes:

Commands

Storage

Directory: Bridges directory (e.g., thinking/bridges/ under your configured workspace root)

Each bridge is a YAML file: {date}-{seq}-{source}-to-{target}.yaml

Example: 2026-04-08-1-hp-to-brand.yaml

Sequence: Within a day, increment seq (1, 2, 3...). Check existing files for the day to determine next seq.

Schema

source: HP
target: BR
archetype: narrative
emoji: 📖
description: "Philosopher council on construct AI → reframes human-centric positioning from marketing to philosophy"
direction: one-way  # one-way | bidirectional
strength: potential  # active | potential | theoretical
context: "During introspect session, realized philosopher encounters are unique differentiator"
date: 2026-04-08

Fields:

• source, target: Project alias (uppercase, from config keys)
• archetype: One of the 10 codes
• emoji: Archetype emoji
• description: The bridge itself — what flows from source to target
• direction: one-way (A→B only) or bidirectional (A↔B, create one file with note)
• strength: active (happening now), potential (could happen, not activated), theoretical (speculative)
• context: Optional — what triggered the discovery (session, meeting, realization)
• date: ISO date

Capture (/bridge <args>)

Parse Arguments

Input: /bridge HP → BR: philosopher encounters reframe human-centric positioning

1. Split on → to get source and rest
2. Split rest on : to get target (+ optional [type]) and description
3. Resolve aliases against config keys (case-insensitive). If no match, fuzzy-match against name fields.
4. If [type] present, use it; otherwise auto-detect archetype

Auto-Detect Archetype

If no explicit type, use two signals:

Signal 1 — Keywords in description:

• "pattern", "framework", "method", "learned", "reusable" → knowledge
• Person name (check config stakeholders) or "carries context", "cross-pollinates" → people
• "story", "credibility", "proof", "case study" → narrative
• "test ground", "lab", "experiment", "tried in" → terrain
• "loop", "feeds back", "cycle" → flywheel
• "brand", "who I am", "positioning", "identity" → identity
• "admin", "bureaucracy", "same skill", "transfers" → complexity
• "local", "geographic" → local
• "future", "optionality", "if it works", "unlocks" → option
• "introspect", "philosopher", "reframe", "reshape" → mirror

Signal 2 — Config context:

• If source or target has flywheel_role: terrain → lean toward terrain
• If source or target has flywheel_role: mirror → lean toward mirror
• If a stakeholder name appears in description and has also_in → people

If ambiguous, default to knowledge and mention in response.

Detect Direction & Strength

• Default: one-way, potential
• If description contains "↔" or "bidirectional" or "both ways" → bidirectional
• If description contains "already", "happening", "active", "doing this" → active
• If description contains "could", "should", "would", "not yet" → potential
• If description contains "maybe", "speculative", "in theory" → theoretical

Write File

1. Guard: check workspace root is configured. If not: ⚠️ Workspace root not set. Configure via environment variable (e.g. export PRAXIS_DIR="$HOME/dev/praxis")
2. Create bridges directory if it does not exist
3. Determine seq: count existing {date}-* files + 1
4. Write YAML file
5. Respond (one line): 🔗 Bridge #N: {emoji} {source} → {target} ({archetype}) — {short desc}
6. Weekly nudge (optional): count bridges this week. If ≥3 involving same project pair: append 📊 {N} bridges this week involving {pair}. Consider updating strategic bridges during review.
7. Resume prior work immediately.

List (/bridge list [project])

1. Glob for all YAML files in bridges directory
2. Read each file, parse YAML
3. If project filter: match against config aliases or names (case-insensitive)
4. Sort by date desc, show last 10
5. Display:

🔗 Bridges (last 10)
  1. 2026-04-08 📖 HP → BR: philosopher encounters reframe positioning (potential)
  2. 2026-04-08 🧠 BNP → HP: observability patterns = atelier content (active)
  3. 2026-04-07 👤 HP ↔ SL: Matthieu carries context both ways (active)

If empty: 🔗 No bridges captured yet. Use /bridge <source> → <target>: <description>

Map (/bridge map)

1. Read config for project names (display labels)
2. Read all bridge files
3. Generate mermaid graph using config names as node labels:

graph LR
    classDef active fill:#90EE90,stroke:#333,color:#000
    classDef potential fill:#FFE4B5,stroke:#333,color:#000
    classDef theoretical fill:#FFB6C1,stroke:#333,color:#000

    HP["Homo Promptus"] -->|"📖 narrative"| BR["Personal Brand"]:::active
    DS["Digital Stoic"] -->|"🧠 patterns"| HP:::potential
    HP <-->|"👤 Matthieu"| SL["Slasheo"]:::active

1. Group by strength (active=green, potential=orange, theoretical=pink)
2. Output the mermaid block

Stats (/bridge stats)

1. Read all bridge files
2. Read config for tier info
3. Count by: project (as source + target), archetype, strength, tier, this-week vs all-time
4. Display:

📊 Bridge Stats
  This week: 5 bridges
  All time: 23 bridges

  By project (top 5):
    HP: 12 (6→, 6←) [tier 1]
    BR: 8 (2→, 6←) [tier 1]
    DS: 7 (5→, 2←) [tier 1]

  By archetype:
    🧠 knowledge: 8
    📖 narrative: 6
    👤 people: 4

  By strength:
    🟢 active: 9
    🟡 potential: 11
    🔴 theoretical: 3

  Tier 2 bridges: 3 (VN→HP, VN→BR, LW→HP)

Key Behaviors

• One-line capture response. Never add commentary about bridge content.
• Resume immediately. After capture, pick up prior conversation exactly where it left off.
• Store verbatim. No reformulation of user's description.
• Auto-detect but don't over-think. If archetype is ambiguous, pick the closest and move on.
• Weekly nudge, not nag. Mention reconciliation opportunity only when pattern is clear (≥3 same pair).
• No GTD writes. This skill only writes to the bridges directory. Strategic bridge summaries are updated manually during weekly review.
• Config-driven. All project aliases come from the configured project YAML. If a project isn't in config, warn and suggest adding it.

When to Use

• A cross-project pattern or shared method surfaces mid-conversation and you want to capture it before the context is lost.
• You hear yourself (or the user) say phrases like "this is the same as", "this connects to", "this feeds into", or "same pattern as" another project.
• A person is mentioned who works across two projects and carries meaningful context between them (people-bridge signal).
• You finish a session and realise one project generated a story, case study, or proof point that strengthens another.
• A project is being used as a live test-bed for methods intended for a different project (terrain signal).

When Not to Use

• The connection is purely administrative (shared calendar, same Slack channel) with no knowledge or value transfer.
• Both "projects" are the same project under different names — use project config aliasing instead.
• The user is mid-decision and does not want their flow interrupted; wait for a natural pause or explicit /bridge invocation.
• The link is already captured: check /bridge list before writing a duplicate.
• You are inside a weekly review session already updating strategic summaries — bridges are for in-the-moment capture, not retrospective logging.

Anti-Patterns

• NEVER reformulate the user's description — store the exact wording as given. Why: paraphrasing introduces your interpretation and erases the original mental model that triggered the insight.
• NEVER add unsolicited commentary on bridge content — the response is one line only. Why: this skill is a capture tool, not an analysis tool; commentary derails the primary conversation.
• NEVER write to GTD task files or project artifacts — only write to the bridges directory. Why: mixing bridge captures into task lists pollutes both systems and breaks single-responsibility.
• NEVER guess a project alias that is not in config — warn and prompt the user to add it. Why: silent alias invention creates inconsistent data that breaks /bridge list, /bridge map, and stats aggregation.
• NEVER skip the seq check — always count existing files for the day before assigning a sequence number. Why: collisions overwrite existing bridge captures with no warning.

Usage Examples

Capturing a knowledge bridge mid-session:

# User is in a meeting and realises a framework from one project applies to another
/bridge PROJ-A → PROJ-B: observability patterns from service mesh apply directly to the atelier content structure
# Skill writes: 2026-04-11-1-proj-a-to-proj-b.yaml  (archetype: knowledge, strength: potential)
# Response: 🔗 Bridge #1: 🧠 PROJ-A → PROJ-B (knowledge) — observability patterns from service mesh apply directly to the atelier content structure

Capturing a people-bridge with bidirectional flow:

# A stakeholder carries context in both directions between two projects
/bridge PROJ-A ↔ PROJ-C [people]: Matthieu carries positioning context both ways and cross-pollinates priorities
# Skill detects '↔' → direction: bidirectional; 'Matthieu' in stakeholders → archetype: people
# Response: 🔗 Bridge #2: 👤 PROJ-A ↔ PROJ-C (people) — Matthieu carries positioning context both ways

Listing recent bridges and generating a visual map:

/bridge list PROJ-A
# Returns last 10 bridges involving PROJ-A, sorted by date desc

/bridge map
# Returns a mermaid graph block with all captured bridges coloured by strength

References

• Personal Knowledge Management — Linking Your Thinking
• YAML Specification — Block Scalars