A
software engineeringbridge

Bridge: Cross-Project Connection Capture

Capture a cross-project connection the moment it surfaces, such as a shared pattern, a person carrying context between projects, a story that lends another project credibility, a feedback loop. Use when one project feeds, reuses, reinforces another: 'connects to', 'feeds into', 'same pattern as'. Writes one YAML file per bridge to a bridges directory, with list, map and stats subcommands.

npx skills add github:pantheon-org/tekhne --skill software-engineering--bridge

Capture a bridge while you are still in context. Keep it in the bridges directory, never in project artifacts.

Principles

  • Capture fast, then step aside: answer in one line and resume the conversation that produced the link.
  • Store the user’s words, not yours, because a paraphrase erases the mental model that triggered the link.
  • Choose an honest default over a confident guess; a wrong rare archetype hides in the stats, while a visible knowledge default gets corrected.
  • Write to the bridges directory only.

When to Use

  • Use it when the user says “this connects to” or “same pattern as” another project.
  • Use it when a person who works across two projects carries context between them.
  • Use it when a session produces a story or proof point that strengthens another project.
  • Capture a stated link even without /bridge, provided both projects resolve from config.

When Not to Use

  • Avoid capturing administrative links (shared calendar, same channel) that move no knowledge.
  • Avoid capturing when both names point at one project; fix the alias in config instead.
  • Stop and wait when the user is mid-decision, until a natural pause or an explicit /bridge.
  • Check for an existing bridge first, and never recapture a link that is already stored.
  • Avoid capturing during a weekly review, because bridges are for in-the-moment capture.

Commands

Run /bridge <src> → <tgt>: <desc> to capture, adding [type] after the target to force an archetype. Read list, map and stats output, then run /bridge list [project], /bridge map or /bridge stats to read bridges back.

Capture Procedure

  1. Read the project config at $PRAXIS_DIR. It holds aliases, names, tiers, flywheel roles and stakeholders with also_in. If it is missing, stop with ⚠️ No project config found. Create it with your project definitions.
  2. Split the input on → or ↔ for the source, then on : for the target, any [type] and the description.
  3. Resolve both aliases against config keys, case-insensitively, then fuzzy-match against name. If either fails, write nothing. Warn and suggest adding the project to config.
  4. Pick the archetype. Use [type] when given, otherwise apply archetype detection. When the signal is weak, use knowledge and say so.
  5. Set the direction. Use bidirectional for ↔, “bidirectional” or “both ways”, otherwise one-way.
  6. Set the strength. Check hedges first (“maybe”, “in theory” give theoretical), then present tense (“already”, “carries” give active), then “not yet”, “should”, “if it works” for potential. Default to potential.
  7. Check for a duplicate, then write the file following storage and schema.
  8. Answer with one line, then resume the prior conversation. Use ↔ for bidirectional bridges and add , defaulted in the brackets after a defaulted archetype:
🔗 Bridge #N: {emoji} {source} → {target} ({archetype}) — {short desc}

When three or more bridges this week share one project pair, append 📊 {N} bridges this week involving {pair}. Update strategic bridges during review.

Take the highest number used today, add one, then confirm the file parses:

last="$(ls "$dir" | sed -n "s/^$(date +%F)-\([0-9]*\)-.*/\1/p" | sort -n | tail -1)"; seq=$(( ${last:-0} + 1 ))
yq '.' ./thinking/bridges/"$file" > /dev/null

Anti-Patterns

  • NEVER reformulate the user’s description. WHY: a paraphrase adds your interpretation and erases the original mental model.
  • NEVER comment on the bridge content. Keep the response to one line, because commentary derails the conversation.
  • NEVER write to GTD files or project artifacts; mixing captures into task lists pollutes both.
  • NEVER invent an alias that is not in config; invented aliases break list, map and stats.
  • NEVER count files to get the sequence number, because after a deletion the count collides and overwrites a capture. Always use the highest number plus one.
  • NEVER guess a rare archetype (local, mirror, complexity) on one keyword; the pitfall is a mislabel that skews the stats unseen.
  • NEVER hardcode one-way and potential; run steps 5 and 6 so the stats do not repeat a wrong relationship.
# BAD: "Matthieu carries context both ways" stored with the defaults
direction: one-way
strength: potential
# GOOD: "both ways" is bidirectional, "carries" is present tense
direction: bidirectional
strength: active

References

Edit this page on GitHub