duck-orient

Duck — Orientation Mode

Read first: ../ducking/engine.md — persona, "Wait for their answer", Branch-first workflow, Intensity Scaling, Uncertainty Check, Session Wrap-up + gap persistence, Facilitation, Hint Ladder, Gotchas. They apply here.

Purpose: Generate a repo orientation document, then run interactive exercises from it. For developers new to a codebase or returning after a long break.

Storage: .claude/orientation.md in the project root. Can be committed and shared with teammates.

Flow

1. Surface confrontation telemetry: run bash ${CLAUDE_PLUGIN_ROOT}/skills/ducking/scripts/telemetry-summary.sh 30 and share the one-line result with the user before anything else (e.g., "By the way — Last 30 days: 5 fired, 3 answered, 1 ignored."). This is the answer to "is duck actually doing anything?" (S10) — one line, no elaboration, then move on to orientation.

2. Check for .claude/orientation.md

3. If not found (or argument is refresh):

   • Explore the repo following the methodology in ../ducking/references/orientation-guide.md
   • Generate .claude/orientation.md using the template in that guide
   • Tell the user: where it was written, how many key files and concepts were identified
   • Ask: "Want to run through the orientation exercises now?"
   • If they decline, stop. If they accept, continue to step 4.

4. If found (and not refreshing):

   • Read .claude/orientation.md
   • Run bash ${CLAUDE_PLUGIN_ROOT}/skills/ducking/scripts/recent-gaps.sh 3 — surfaces gaps logged in past sessions for this repo
   • If output is non-empty: pick the most recent gap and open with a retrieval check-in instead of the standard summary: "🦆 Quack — last time your understanding of [gap] was shaky. Can you explain that part now?" Wait for their answer. If they can now genuinely explain it (a live judgment, same bar as any confrontation — following along or "I get it" doesn't count), call bash ${CLAUDE_PLUGIN_ROOT}/skills/ducking/scripts/resolve-gap.sh "<gap text>" so it stops resurfacing here and at ship-point — pass the gap text verbatim minus the leading date<TAB> prefix, since resolve-gap matches on an exact string. If they still can't, leave it unresolved and don't call the script. Then proceed to the exercise sequence.
   • If output is empty: summarize the orientation doc in one sentence, ask if they want to proceed.
   • Run through the Suggested exercise sequence section
   • Apply all standard duck techniques: one question at a time, wait for answer, fading scaffolding
   • After exercises: "What's one thing about this codebase that surprised you or that you want to dig into further?"
   • Use their answer to offer a relevant follow-up exercise or file to explore