@albinocrabs/feynman 0.2.2 → 0.2.5

package/examples/c4-platform-diagramming.md

@@ -0,0 +1,112 @@
+# C4-Style Architecture and Request Flow
+
+## Question
+
+> Sketch a clean C4-style view for an AI documentation tool and show the
+> normal request flow. I want context, container split, component split, and a
+> clear status view for blockers.
+
+## Without feynman
+
+The tool has three users: author, reviewer, and operator. It includes a web
+client, a prompt gateway API, a rules engine, a diagram renderer, and a
+quality service that validates responses before returning them. There is
+SSO-based auth, storage for templates, and a shared observability channel.
+If the rules fail to load, the request still needs a deterministic fallback to
+text mode so the user is not blocked.
+
+## With feynman
+
+### C4 context
+
+```
+feynman-system
+├── actors
+│   ├── [Document Author]
+│   ├── [Reviewer]
+│   └── [Operator]
+├── containers
+│   ├── [Web Client]
+│   ├── [Prompt Gateway API]
+│   ├── [Rule Service]
+│   ├── [Diagram Renderer]
+│   └── [Quality Service]
+└── external systems
+    ├── [SSO]
+    ├── [Template Storage]
+    ├── [Model Provider]
+    └── [Observability]
+```
+
+### C4 container run
+
+```
+[Document Author] --> [Web Client]
+                      |
+                      v
+[Reviewer]       --> [Prompt Gateway API]
+                      |
+                      v
+                      [Auth + Rate Limit]
+                              |
+                              +-- unauthorized --> [403 / 401]
+                              |
+                              +-- authorized
+                                    |
+                                    v
+                               [Rule Service]
+                                    |
+                                    +-- rule set miss --> [Text fallback]
+                                    |
+                                    +-- rule set hit
+                                          |
+                                          v
+                                     [Diagram Renderer]
+                                          |
+                                          v
+                                       [Quality Service]
+                                          |
+                                          +-- blocked --> [Recovery Plan]
+                                          |
+                                          +-- pass --> [JSON response]
+                                          |
+                                          v
+                                  [Observability publish]
+                                          |
+                                          v
+                                   [Document Author/Reviewer]
+```
+
+### Architecture split
+
+```
+criterion      | Context (C1)        | Containers (C2)      | Components (C3)
+---------------|---------------------|----------------------|----------------------
+Main question  | Who talks to what   | Who owns boundary    | Who owns behavior
+Primary risk   | Missing actor path   | Wrong trust boundary  | Rule fallback bug
+Owner now      | Product + Ops       | Backend + Security    | Runtime rule authors
+```
+
+### Why this helps
+
+```
+┌─ Delivery readiness ────────────┐
+  context map     done
+  container flow   done
+  component split done
+  risk hotspots   identified
+└─────────────────────────────────┘
+```
+
+## Why this works
+
+Without explicit structure, the explanation is a dense paragraph. With the C4
+perspective, Feynman converts it into:
+- actor/system decomposition,
+- runtime sequence,
+- boundary+fallback behavior,
+- and explicit risk visibility.
+
+The result is understandable quickly and can be reviewed or extended as a
+single architecture baseline.
+

package/examples/context-splitting.md

@@ -0,0 +1,77 @@
+# Context Splitting: Product Initiative to Deploy a New Onboarding Assistant
+
+## Question
+
+> We want to launch a new onboarding assistant next quarter. It touches web UI, backend,
+> legal review, and customer support. How should we split work so leadership can
+> understand risk, dependencies, and rollout order in one view?
+
+## Without feynman
+
+The initiative includes multiple teams and timelines. First we should do discovery and
+alignment between engineering, legal, and support. Then UI and backend work must start,
+because both rely on design contracts. A pilot should run with 10% of new users, then
+global rollout should happen after legal and reliability checks are complete.
+
+## With feynman
+
+Scope decomposition:
+
+```
+[Onboarding assistant]
+  ├── Product & UX
+  │     ├── onboarding copy
+  │     ├── microcopy guardrails
+  │     └── in-app hints
+  ├── Platform
+  │     ├── assistant API
+  │     ├── telemetry events
+  │     └── admin flags
+  ├── Legal & Compliance
+  │     ├── consent text
+  │     └── data retention policy
+  └── Operations
+        ├── runbook
+        ├── on-call drill
+        └── rollback script
+```
+
+Cross-team launch flow:
+
+```
+[Legal approves data flow] --> [Backend API contract ready]
+                                   |
+                                   v
+ [UX/Copy draft] --> [Integration tests] --> [10% pilot]
+                                   |               |
+                           fail --> [fix + retest]   v
+                                                  [60-day rollback check]
+                                   |
+                                   +--> [full rollout]
+```
+
+Dependency safety frame:
+
+- legal-ok: mandatory
+- telemetry path: must emit onboarding_success and onboarding_fail
+- fallback: always-on silent mode if latency > 300ms
+- rollback: kill-switch <2 minutes
+
+Priority lanes:
+
+```
+▲ high
+  legal/consent review
+  backend idempotency
+  kill-switch + rollback readiness
+▼ low
+  copy polishing
+  dashboard cosmetics
+```
+
+## Why this works
+
+The question has nested uncertainty and cross-team constraints. The tree diagram makes
+the decomposition explicit. The flow diagram shows execution order and rework loops.
+The frame and priority lanes turn soft governance requirements into checkable launch
+conditions.

package/examples/feature-planning.md

@@ -0,0 +1,107 @@
+# Feature Planning: Build Internal Search or Use Managed API
+
+## Question
+
+> We need fast text search by title/body tags. Should we build it ourselves or use
+> a managed search service? Compare the options by cost, speed, and maintenance.
+
+## Without feynman
+
+Building search internally gives us full control over ranking but requires schema
+indexing work, query tuning, and ongoing reliability engineering. A managed API
+is faster to deliver and has better relevance out of the box, but it increases
+vendor dependency and recurring cost. We can reduce risk by evaluating latency,
+cost, and maintenance for a 6-month period and then revisiting.
+
+## With feynman
+
+Decision matrix:
+
+```
+Option            | build-internal                  | managed-search-service
+------------------|--------------------------------|--------------------------
+speed-to-market   | 8-12 weeks                    | 1-2 weeks
+query latency     | 60-120ms (with cache)          | 40-80ms
+maintenance       | high (2 engineers, on-call)     | low
+vendor lock-in    | none                           | medium-high
+relevance quality | custom control, tuning effort   | high, pre-tuned
+```
+
+Decision flow:
+
+```
+[Need search by title/body now?] --> [Yes]
+                                   |
+                                   v
+                     [Need search now?] --> [Evaluate managed by default]
+                                                  |
+                                                  v
+                                       [POC in 2 weeks]
+                                                 |
+                           +-------------------- +--------------------+
+                           |                                         |
+                           v                                         v
+                   [Latency/cost ok]                              [No]
+                         |                                         |
+                         +--> [Adopt]                              +--> [Re-open internal build path]
+                               |
+                               +--> [Plan v1 migration in 1 sprint]
+```
+
+Governance priority:
+
+```
+▲ high
+  Vendor contract review (SLA, data residency)
+  Incident drill: provider outage fallback plan
+▼ low
+  UI polish in search result cards
+  Advanced synonym tuning
+```
+
+Phased rollout map:
+
+```
+[Decision]
+  |
+  v
+[POC + telemetry]
+  |
+  +-- latency/cost tests fail? --+--> [Re-scope]
+  |
+  +-- latency/cost tests pass? --> [Fallback path] --> [Adoption path]
+                                  |
+                                  +--> [Cost optimization] --> [Quarterly review]
+```
+
+Rollback frame:
+
+```
+Managed API chosen:
+- fail trigger: P95 > 2x baseline + cost ↑
+- response: cut volume 50%, enable fallback
+- rollback time: 45 min
+- owner: on-call + search guild
+```
+
+Context split before execution:
+
+```
+[Business goal]
+  ├── [Performance]
+  │     ├── latency
+  │     └── availability
+  ├── [Economics]
+  │     ├── direct cost
+  │     └── hidden support cost
+  └── [Risk]
+        ├── lock-in
+        ├── security
+        └── reversibility
+```
+
+## Why this works
+
+The plain comparison becomes explicit with columns, and the execution path becomes
+operational through a flow diagram. This helps teams decide with one view of
+trade-offs and controls.

package/examples/incident-response.md

@@ -0,0 +1,77 @@
+# Incident Response: API Latency Spike and 502s
+
+## Question
+
+> My API started returning intermittent 502s and latency jumped from 120ms to
+> 4s. I have Redis, API pods, and DB replicas. How should we triage and restore
+> service in the next 20 minutes?
+
+## Without feynman
+
+The API has a latency issue. First verify if the issue is traffic-related or a
+deployment regression, then inspect pods, then check cache hit rates, and then
+inspect database query times. If the pods are overloaded, scale horizontally and
+enable degraded mode. If Redis errors increase, fail over to DB reads with a strict
+timeout. If replicas are behind replication lag, move read traffic back to primary
+only and notify users of elevated error rates.
+
+## With feynman
+
+Triage and restore sequence:
+
+```
+[Alert: 502 + latency spike] --> [1) Confirm incident scope]
+                                  |
+                                  +--> [Critical path only]
+                                  |        |
+                                  |        +--> [Disable non-core features]
+                                  |        |
+                                  |        +--> [Enable queue fallback]
+                                  |
+                                  +--> [2) Isolate root layer]
+                                           |
+                                   [Cache regression?]
+                                      |
+                                yes -->|                   |--> no
+                                       v                   v
+                               [Scale API / limit RPS]   [Deployment rollback?]
+                                      |                   |
+                                      pass                    fail
+                                      |                      |
+                                      v                      v
+                             [Service partially stable]
+                                      |                   |
+                                      v                   v
+                               [Resolve]       [Rollback last deploy]
+                                                       |
+                                                       v
+                                         [Restore response rate]
+```
+
+Live status summary:
+
+```
+┌─ Incident Runbook ────────────────────┐
+  step-1        in-progress
+  step-2        pending
+  step-3        pending
+  external-comm on-call-channel
+└───────────────────────────────────────┘
+```
+
+Priority gates:
+
+```
+▲ high
+  API error budget burn
+  Security-sensitive write path (stop writes if needed)
+▼ low
+  Nice-to-have dashboards
+  Cosmetic alert updates
+```
+
+## Why this works
+
+This example combines sequential flow (triage stages), branch isolation, status
+frames, and priority scale. It turns ad-hoc firefighting into an explicit,
+readable execution plan before any action is taken.

package/examples/release-readiness.md

@@ -0,0 +1,73 @@
+# Release Readiness: Monthly Deployment to Production
+
+## Question
+
+> We have a monthly release with API, web, and mobile changes. What gates and
+> rollback triggers do we need before and after deploy?
+
+## Without feynman
+
+Coordinate release notes, run migration checks, execute smoke tests on staging, and
+run targeted regression tests. If deployment passes, monitor key metrics for one hour
+and then announce success. Rollback should be triggered on increased errors or
+critical latency regressions.
+
+## With feynman
+
+```
+[Pre-release plan] --> [Staging deploy]
+                      |
+                      v
+              [Smoke + regression]
+                      |
+             pass ----+---- fail
+              |              |
+              v              v
+        [Production]    [Stop + fix]
+              |
+              v
+        [Observe 60 min]
+              |
+      pass ----+---- fail
+       |              |
+       v              v
+[Done + announce] 
+[Rollback + incident]
+```
+
+Readiness gates:
+
+```
+criterion            | gate type | owner          | must be true
+--------------------|-----------|----------------|----------------------
+migration safety     | schema    | platform       | dry-run + backward-compatible
+auth/checkout smoke  | functional| product qa      | 100% critical paths
+error budget         | reliability| sre            | error rate <= baseline + 0.2%
+security regression  | security  | infosec        | zero new critical findings
+```
+
+Readiness status:
+
+- staging-deploy: done
+- smoke-tests: in progress
+- security-gate: pending
+- rollback-drill: ready
+- comms-draft: in progress
+
+Priority ladder:
+
+```
+▲ high
+  no data loss
+  idempotent migrations
+  auth + checkout paths
+▼ low
+  branding tweaks
+  help-center wording
+```
+
+## Why this works
+
+The flow diagram shows what blocks progression to production and where rollback
+branches back. The gate table gives objective pass criteria. The status frame and
+priority scale separate urgent reliability conditions from polish work.

package/examples/service-migration.md

@@ -0,0 +1,72 @@
+# Service Migration: Move Billing to a New Provider
+
+## Question
+
+> We need to migrate billing from Provider A to Provider B. What is the safest rollout
+> sequence with fallback and acceptance gates?
+
+## Without feynman
+
+Start in read mode to keep both providers enabled, compare charge outcomes for a
+sample of users, run a pilot for low-risk plans, then run a staged migration to
+full traffic with manual approval and rollback checkpoints.
+
+## With feynman
+
+Migration ladder:
+
+```
+[Dual-run mode]
+      |
+      v
+[Replay 30 days of traffic] --> [Compare divergence < 1%] --> [Pilot 5% users]
+      |
+      v
+[Auto-scaling smoke] --> [Pilot 30% users] --> [100% rollout]
+      |
+      +--> [Error rate > threshold] --> [Disable 30% wave]
+      |
+      +--> [Critical incidents] --> [Fallback to A]
+```
+
+Vendor comparison:
+
+```
+Option A (keep)   | Option B (move)      | Hybrid (dual)
+------------------|----------------------|------------------
+steady risk       | new integration risk  | controlled transition
+low complexity     | higher validation    | higher ops cost
+higher cost risk   | lower long-term cost  | medium monitoring
+fast execution     | phased execution      | slower initial step
+```
+
+Go/no-go gates:
+
+- divergence_rate <= 1%
+- failed callbacks < 0.2%
+- latency_p95 <= baseline + 20ms
+- reconciliation queue no growth
+
+Fallback playbook:
+
+- trigger: payment failure spike
+- action: switch traffic to A
+- deadline: < 10 minutes
+- owner: on-call + fintech lead
+
+Execution priority:
+
+```
+▲ high
+  reconciliation accuracy
+  callback reliability
+▼ low
+  brand messaging tweaks
+  custom dashboard layout
+```
+
+## Why this works
+
+В миграции ключевая ценность — показывать не просто шаги, а условия перехода между
+ступенями. Поток делает это явно: переход к следующей стадии возможен только при
+прохождении метрик и готовности fallback.

package/hooks/feynman-activate.js

@@ -31,18 +31,25 @@ process.stdin.on('end', () => {
     if (sessionId && /[/\\]|\.\./.test(sessionId)) process.exit(0);
 
     // Step 2: flag file + first-run bootstrap (D-05, D-07, bug #35713)
-    // True first run: neither flag nor state exists → bootstrap both, then fall through
-    // Intentionally disabled: flag absent but state exists → exit 0 (user ran /feynman off)
+    // True first run: neither flag nor state exists -> bootstrap default full mode.
+    // Intentionally disabled: flag absent + state.enabled=false -> exit 0.
     const flagExists  = fs.existsSync(FLAG_PATH);
     const stateExists = fs.existsSync(STATE_PATH);
     if (!flagExists) {
       if (!stateExists) {
-        // First install — bootstrap everything and activate
+        // First install: bootstrap and activate full mode.
         fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
         fs.writeFileSync(STATE_PATH, JSON.stringify(DEFAULT_STATE, null, 2));
         fs.writeFileSync(FLAG_PATH, DEFAULT_STATE.intensity);
       } else {
-        process.exit(0); // disabled intentionally by user
+        let existingState;
+        try {
+          existingState = { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
+        } catch (_) {
+          process.exit(0);
+        }
+        if (!existingState.enabled) process.exit(0);
+        fs.writeFileSync(FLAG_PATH, existingState.intensity || DEFAULT_STATE.intensity);
       }
     }
 

package/hooks/feynman-session-start.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// feynman — SessionStart hook — injects active diagram rules at session start.
+// UserPromptSubmit still reinforces rules every turn; this primes fresh sessions.
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const HOME        = os.homedir();
+const CLIENT_HOME = process.env.FEYNMAN_HOME || path.join(HOME, '.claude');
+const FEYNMAN_DIR = path.join(CLIENT_HOME, '.feynman');
+const STATE_PATH  = path.join(FEYNMAN_DIR, 'state.json');
+const FLAG_PATH   = path.join(CLIENT_HOME, '.feynman-active');
+const RULES_PATH  = path.join(__dirname, '..', 'rules', 'feynman-activate.md');
+
+const DEFAULT_STATE = { enabled: true, intensity: 'full', injections: 0 };
+const VALID_INTENSITIES = ['lite', 'full', 'ultra'];
+
+function readState() {
+  try {
+    return { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) };
+  } catch (_) {
+    return { ...DEFAULT_STATE };
+  }
+}
+
+function writeState(state) {
+  fs.mkdirSync(FEYNMAN_DIR, { recursive: true });
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+
+function readRules(intensity) {
+  const rulesContent = fs.readFileSync(RULES_PATH, 'utf8');
+  const selected = VALID_INTENSITIES.includes(intensity) ? intensity : 'full';
+  const openMarker  = '<!-- ' + selected + ' -->';
+  const closeMarker = '<!-- /' + selected + ' -->';
+  const i1 = rulesContent.indexOf(openMarker);
+  const i2 = rulesContent.indexOf(closeMarker, i1);
+  if (i1 === -1 || i2 === -1) return '';
+  return rulesContent.slice(i1 + openMarker.length, i2).trim();
+}
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    if (input.trim()) {
+      const data = JSON.parse(input);
+      const sessionId = data.session_id || '';
+      if (sessionId && /[/\\]|\.\./.test(sessionId)) process.exit(0);
+    }
+
+    const stateExists = fs.existsSync(STATE_PATH);
+    const flagExists = fs.existsSync(FLAG_PATH);
+    const state = readState();
+
+    if (!stateExists) {
+      writeState(state);
+    }
+
+    if (!state.enabled) {
+      try { fs.unlinkSync(FLAG_PATH); } catch (_) {}
+      process.exit(0);
+    }
+
+    if (!flagExists) {
+      fs.writeFileSync(FLAG_PATH, state.intensity || DEFAULT_STATE.intensity);
+    }
+
+    const rulesText = readRules(state.intensity);
+    if (!rulesText) process.exit(0);
+
+    // SessionStart accepts plain stdout as context, matching caveman's hook shape.
+    process.stdout.write(rulesText);
+  } catch (_) {
+    process.exit(0);
+  }
+});

package/hooks/hooks.json

@@ -1,14 +1,24 @@
 {
   "description": "Inject feynman ASCII diagram rules before each Claude Code prompt.",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }

package/hooks.json

@@ -1,13 +1,24 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-session-start.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-activate.js\"",
-            "timeout": 5,
-            "statusMessage": "Injecting diagram rules..."
+            "timeout": 5
           }
         ]
       }