/orienting-codebases

name: orienting-codebases
description: >-
  Interactive codebase orientation for a HUMAN who wants to learn the code.
  Runs the same tree-sitting + featuring pipeline as exploring-codebases but
  synthesizes it into guided exercises and an HTML teaching artifact rather
  than an analysis document. Use for "orient me to this repo", "teach me
  this codebase", "walk me through this code", "learning orientation", or
  when someone wants genuine comprehension rather than a task completed. The
  audience is the test: if nobody is being taught and the goal is to get
  work done, use exploring-codebases instead.
metadata:
  version: 0.4.0
  license: CC-BY-4.0
  lineage: >-
    Pedagogical design adapted from DrCatHicks/learning-opportunities
    (orient skill + PRINCIPLES.md). Pipeline from exploring-codebases.
    Presentation via composing-html.

Orienting Codebases

Interactive codebase orientation for the human, not the agent. Same tree-sitting + featuring pipeline as exploring-codebases, but synthesizes into guided HTML exercises via composing-html instead of analysis documents. See README.md for design rationale.

Pipeline

0. Setup (once per session)

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py
export COMPOSE=/mnt/skills/user/composing-html/scripts/build.py

1. Get the repo

OWNER=... REPO=... REF=main
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1

For local repos, skip the curl — point directly at the path.

2. Structural scan

$PYTHON $TREESIT /tmp/$REPO --stats

3. Feature gathering

$PYTHON $GATHER /tmp/$REPO \
  --skip tests,.github,node_modules --source-budget 8000

4. Targeted source extraction

For each exercise target identified from gather output, extract the actual source using treesit queries:

# Entry point source
$PYTHON $TREESIT /tmp/$REPO --no-tree 'source:main'

# Specific function for an exercise
$PYTHON $TREESIT /tmp/$REPO --no-tree 'source:validate_token'

# Imports for a hub file
$PYTHON $TREESIT /tmp/$REPO --no-tree 'imports:src/api.py'

This source feeds directly into the HTML artifact — the user sees real code, syntax-highlighted, without having to navigate the repo.

**Do not show raw pipeline output to the user.** It's material for exercise design. The user sees HTML artifacts and conversation.

Orientation session

After the pipeline steps, synthesize into an interactive orientation. Three phases.

Phase A: Framing (1 message, no artifact)

Summarize the repo in ONE sentence (what it does, who it's for). Then:

> I can walk you through a hands-on orientation — about 15 minutes, > two exercises that'll give you a working mental model of this codebase. > Want to try it?

Do not start exercises without confirmation.

Phase B: Exercises (2 exercises, interactive)

For each exercise, generate an HTML artifact using composing-html's `freeform` template, then continue the conversation around it.

Artifact structure per exercise

Build a spec with `body_html` containing:

<section class="stack">
  <div class="eyebrow">EXERCISE 1 OF 2</div>
  <h2>[Exercise title]</h2>

  <div class="card">
    <div class="eyebrow">CONTEXT</div>
    <p>[Brief explanation of what this code does in the system
       and why it matters for orientation.]</p>
  </div>

  <div class="card">
    <div class="eyebrow">CODE</div>
    <pre><code>[Actual source extracted by treesit — entry point,
function, config, imports, or test names. Escaped properly.]</code></pre>
  </div>

  <details class="card">
    <summary>
      <span class="badge badge--clay">Your turn</span>
      [Specific comprehension/synthesis question]
    </summary>
    <div style="margin-top:1rem">
      <div class="eyebrow">KEY POINTS</div>
      <p>[Pre-generated feedback covering what the code reveals about
         the system's architecture, design decisions, or workflow.
         This is the "answer key" — hidden until clicked.]</p>
    </div>
  </details>
</section>

Answers live inside `<details>` — the DOM hides them until the user clicks. Do not preview or summarize the key points in chat after presenting the artifact; that defeats the exercise.

Build and present the artifact:

python3 $COMPOSE build freeform --spec /tmp/exercise_N.json --out /tmp/exercise_N.html

Two interaction modes

After presenting the artifact, tell the user:

> Take a look at the code and the question. You can either: > - **Tell me your answer** in chat and I'll give you specific feedback > - **Click to reveal** the key points in the artifact when you're ready

If they respond in chat: give personalized feedback based on what they actually said — confirm what's right, be specific about gaps, explore misconceptions. This is pedagogically richer than pre-canned feedback.

If they click through: that's fine too — the artifact's hidden feedback covers the essential points. Move to the next exercise.

Exercise design from pipeline signals

Each exercise type maps to specific pipeline output:

**Entry-point walkthrough** — gather found clear entry points: Show the main function/handler source. Ask what the program does on startup and what the 2-3 most important operations are.

**Architecture synthesis** — treesit --stats shows clear directory structure: Show the directory tree with file counts and symbol density. Ask what the system's main components are and how they relate.

**Dependency detective** — gather found import clusters: Show a hub file's imports. Ask what the import list reveals about the file's