/discovery

Process any source of customer context — raw or already-structured — and update the customer's context files.

Step 0: Parse inputs

The customer name is the first argument. Everything after it is the source content — a transcript, notes, handoff doc, briefing, RFP response, or any other inbound material about the customer.

If no customer name is provided: ask "Which customer? (e.g. /discovery acme <source doc>)" If no source content is provided after the name: ask "Paste the source content below — a transcript, handoff doc, briefing, or notes."

Note the source type at the top of the discovery file (Step 6): Source: <transcript | handoff | briefing | RFP | notes | other>. This is part of the audit trail — six months later, knowing whether a decision came from your own call vs. an inherited doc is important context.

When the source is already structured (e.g., a Solution Blueprint with sections like "Pain Points" and "Strategic Priorities"), treat it as input not output: extract the same six dimensions below, but expect more pre-organized content and less inference work. The stated-vs-real-problem distinction is still worth making — synthesized docs are usually the upstream author's take, not the customer's raw words.

Set CUSTOMER_NAME from the first argument.

Step 1: Check session marker

MARKER="/tmp/fdestack-session-$CUSTOMER_NAME"
if [ -f "$MARKER" ]; then
  MARKER_TS=$(cat "$MARKER" | grep '^ts=' | cut -d= -f2)
  NOW=$(date +%s)
  AGE=$(( NOW - MARKER_TS ))
  if [ "$AGE" -lt 43200 ]; then
    echo "MARKER_OK=true"
  else
    echo "MARKER_STALE=true AGE_H=$(( AGE / 3600 ))"
  fi
else
  echo "MARKER_MISSING=true"
fi

If MARKER_MISSING=true or MARKER_STALE=true:

Run /customer-context $CUSTOMER_NAME first, then retry /discovery. (Context must be loaded this session to ensure you're working with current information.)

Stop. Do not proceed.

Step 2: Load cross-customer learnings

LEARNINGS_FILE="$HOME/.fdestack/learnings.jsonl"
if [ -f "$LEARNINGS_FILE" ] && [ -s "$LEARNINGS_FILE" ]; then
  tail -5 "$LEARNINGS_FILE" | jq -r '"[learning] " + .key + ": " + .insight' 2>/dev/null || true
fi

If relevant past learnings exist (e.g., similar customer type, similar problem), note them in your analysis — "Prior learning: [x] — watch for this pattern here."

Step 3: Transcript length check

Estimate word count from the transcript length. If the transcript appears very long (rough heuristic: more than ~50 paragraphs or obvious multi-hour raw transcript with timestamps on every line), note:

This is a long transcript — I'll extract what matters. For faster runs next time, paste only the key sections (decisions, action items, new info).

Then proceed normally. Do not truncate or refuse to process.

Step 4: Read current customer context

Read these files to understand existing knowledge before extracting from the transcript:

• customers/<name>/profile.md
• customers/<name>/stack.md
• customers/<name>/stakeholders.md
• customers/<name>/unknowns.md

This lets you identify what's NEW (not already captured) and what CONFLICTS with existing context.

Step 5: Extract from transcript

Working through the transcript, identify:

1. New stack info — tools, APIs, languages, data systems, auth patterns, rate limits, constraints mentioned
2. New stakeholders — people mentioned by name or role who aren't in stakeholders.md
3. Stated problem — what the customer said they want ("we need X")
4. Real problem — what you infer from subtext, what wasn't said, what seems to actually be driving this
5. Open questions — things the customer said they'd find out, things that came up without resolution, things you need to follow up on

6. Context conflicts — anything that contradicts what's currently in the context files. For each conflict, use AskUserQuestion to ask the FDE which version is canonical before writing anything. Format:

   D<N> — Context conflict on <subject>
   ELI10: <stakeholders.md|stack.md|...> says one thing; this <transcript|
   handoff doc|...> says another. Both can't be true. Which is current?
   Stakes if we pick wrong: Wrong choice silently propagates into every
   future Session Brief and skill output until corrected.
   Recommendation: <whichever is more recent / from a more authoritative
   source>, because <one-line reason>.
   Pros / cons:
   A) Trust the existing context file (recommended if older but
      authoritative) — keeps continuity, requires no edit
      ✅ No risk of overwriting a deliberate prior decision
      ❌ Discards new info that might be more accurate
   B) Trust the new source — overwrite the existing entry
      ✅ Reflects the most recent signal
      ❌ Loses the prior decision's context (capture in decisions.md)
   C) Both are partially right — let me edit by hand
      ✅ Surfaces the nuance neither pure choice captures
      ❌ Slowest; requires FDE to interrupt the discovery flow
   Net: A preserves history; B updates fast; C is for the messy real case.

   For each FDE choice: if A, leave the existing entry untouched and append a one-line note in the discovery file's ## Context Conflicts section ("FDE confirmed <existing version> is current; <new source>'s claim discarded"). If B, overwrite the existing entry and log the change in decisions.md. If C, pause Step 5 so the FDE can edit.

Step 6: Write discovery file

Determine the meeting date. If the transcript contains a **Date:** or Date: line near the top, use that. Otherwise default to today ($(date +%Y-%m-%d)). If you're unsure, ask the FDE once: "What date should this discovery be tagged with? (default: today)"

Set MEETING_DATE accordingly and use it for both the filename and the commit message in Step 8.

Set FDE_NAME="$(git config user.name)" so the "FDE:" line renders the real name, not the literal placeholder.

If customers/<name>/discovery-<MEETING_DATE>.md already exists (multiple meetings same day, or rerunning /discovery), append a suffix:

DISCOVERY_FILE="customers/$CUSTOMER_NAME/discovery-$MEETING_DATE.md"
if [ -f "$DISCOVERY_FILE" ]; then
  i=2
  while [ -f "customers/$CUSTOMER_NAME/discovery-$MEETING_DATE-$i.md" ]; do
    i=$((i + 1))
  done
  DISCOVERY_FILE="customers/$CUSTOMER_NAME/discovery-$MEETING_DATE-$i.md"
fi

Then write to $DISCOVERY_FILE:

# Discovery: <YYYY-MM-DD>
FDE: <git user.name>

## New Stack Info
[bullets — only things not already in stack.md]

## New Stakeholders
[name, role, notes — only people not already in stakeholders.md]

## Stated Problem
[one paragraph — what the customer said they want]

## Real Problem (inferred)
[one paragraph — what you think is actually going on based on subtext]

## Open Questions / Follow-ups
[bullets — things to find out or follow up on]

## Context Conflicts
[anything that contradicts existing context files — flag for FDE to reconcile]
[if none: "None — transcript is consistent with existing context."]

## Updates Made
[list of which files were updated and what changed]

Step 7: Update context files in place

For each item extracted in Step 5:

• New stack info → append to customers/<name>/stack.md under the relevant section
• New stakeholders → append to customers/<name>/stakeholders.md under the relevant section
• Open questions → append to customers/<name>/unknowns.md under the appropriate risk level (default MED unless clearly HIGH)
• Context conflicts → note in the discovery file; do NOT silently overwrite existing context. Ask the FDE: "stakeholders.md says X but the transcript says Y — which is current?"

Update the ## Last Updated line in each file you modify.

Step 8: Commit

git add "customers/$CUSTOMER_NAME/"
git commit -m "discovery: $CUSTOMER_NAME $MEETING_DATE"

No confirmation prompt for discovery — the FDE just reviewed the extracted output in Steps 6-7. If the commit fails (e.g., nothing staged), note "Nothing new to commit."

Step 9: Check for cross-customer learnings

After updating context, consider: does anything from this transcript represent a pattern likely to appear with other customers? Examples:

• A surprising technical constraint (e.g., "their Snowflake environment doesn't allow UDFs")
• An organizational pattern (e.g., "legal review takes 6 weeks at companies this size")
• An approach that worked (e.g., "showing the demo before the technical deep-dive changed the conversation")

If yes, ask: "This seems like a generalizable pattern — want me to save it to your learnings for future engagements?"

If yes:

jq -nc \
  --arg skill "discovery" \
  --arg key "<short-key>" \
  --arg insight "<one sentence>" \
  --arg confidence "7" \
  --arg source "observed" \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '{skill:$skill,key:$key,insight:$insight,confidence:($confidence|tonumber),source:$source,ts:$ts}' \
  >> "$HOME/.fdestack/learnings.jsonl"
echo "Saved to learnings."

Print a summary: "Discovery complete. Updated [list of files changed]. [N] open questions added to unknowns.md."