codecall 1.3.0 → 1.5.0

package/plugins/codecall/skills/codecall/references/drill-receipt-template.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<!-- Fill every double-brace placeholder. Keep the meta tags: later sessions read them for the streak line. -->
+<meta name="codecall-mode" content="drill">
+<!-- "found" or "missed". -->
+<meta name="codecall-drill" content="{{FOUND_OR_MISSED}}">
+<meta name="codecall-hints" content="{{HINTS}}">
+<meta name="codecall-minutes" content="{{MINUTES}}">
+<meta name="codecall-date" content="{{DATE}}">
+<!-- The mapped concept the bug exercised, e.g. "http-status-codes:ok" (ok means found with at most two hints); leave content empty when nothing was mapped. -->
+<meta name="codecall-concepts" content="{{MAPPED_CONCEPT_OR_EMPTY}}">
+<title>codecall drill · {{AREA}}</title>
+<style>
+  :root { --bg:#fbfaf7; --ink:#151515; --muted:#6b6760; --line:#e4e0d8; --ok:#1f7a4d; --no:#b3261e; --accent:#2b3e8c; }
+  @media (prefers-color-scheme: dark) { :root { --bg:#161513; --ink:#ece8e0; --muted:#9a948a; --line:#2c2a26; --ok:#5fc48d; --no:#f28b82; --accent:#9fb0ff; } }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--ink); font: 18px/1.45 ui-sans-serif, -apple-system, "Segoe UI", Inter, Roboto, sans-serif; }
+  main { max-width: 720px; margin: 0 auto; padding: 48px 24px 64px; }
+  .brand { font-size: 13px; letter-spacing: .12em; text-transform: uppercase; color: var(--muted); }
+  h1 { font-size: 28px; line-height: 1.2; margin: 8px 0 4px; }
+  .date { color: var(--muted); font-size: 15px; margin-bottom: 28px; }
+  .score { font-size: 56px; font-weight: 700; line-height: 1; margin: 0 0 4px; }
+  .score small { font-size: 18px; font-weight: 500; color: var(--muted); margin-left: 8px; }
+  .streak { color: var(--muted); font-size: 15px; margin-bottom: 32px; }
+  h2 { font-size: 13px; letter-spacing: .12em; text-transform: uppercase; color: var(--muted); margin: 32px 0 12px; }
+  ul { list-style: none; padding: 0; margin: 0; }
+  li { padding: 10px 0; border-top: 1px solid var(--line); }
+  li:last-child { border-bottom: 1px solid var(--line); }
+  .concept { display: grid; grid-template-columns: 28px 1fr; gap: 8px; align-items: baseline; }
+  .ok { color: var(--ok); } .no { color: var(--no); }
+  .concept b { display: block; }
+  .concept span { color: var(--muted); font-size: 16px; }
+  .points li::before { content: "→ "; color: var(--accent); }
+  .deeper { display: block; margin-top: 4px; font-size: 15px; color: var(--muted); }
+  .result.ok { color: var(--ok); } .result.no { color: var(--no); }
+  .deeper a { color: var(--accent); }
+  footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
+  @media print { body { background: #fff; color: #000; } main { padding: 0; } }
+</style>
+</head>
+<body>
+<main>
+  <div class="brand">codecall drill</div>
+  <h1>{{AREA}}</h1>
+  <div class="date">{{DATE}} · {{DIFFICULTY}}</div>
+
+  <!-- class="result ok" with "Found it" or class="result no" with "Missed it". -->
+  <p class="score result ok">{{FOUND_IT_OR_MISSED_IT}}<small>{{MINUTES}} min · {{HINTS}} of 4 hints</small></p>
+  <div class="streak">{{STREAK_LINE_OR_EMPTY}}</div>
+
+  <h2>The bug</h2>
+  <ul>
+    <!-- Keep the deeper line only for a missed drill whose bug maps to a concept card, with that card's links (drop the second link when the card has one); delete it otherwise. -->
+    <li class="concept"><span class="no">●</span><div><b>{{BUG_KIND}}</b><span>{{FILE_NAME}}: {{WHY_IT_CAUSED_THE_SYMPTOM}}</span><span class="deeper">Go deeper: <a href="{{LINK_1_URL}}">{{LINK_1_TEXT}}</a> · <a href="{{LINK_2_URL}}">{{LINK_2_TEXT}}</a></span></div></li>
+  </ul>
+
+  <h2>What went well</h2>
+  <ul class="points">
+    <li>{{WENT_WELL}}</li>
+  </ul>
+
+  <h2>Habit to work on</h2>
+  <ul class="points">
+    <li>{{HABIT}}</li>
+  </ul>
+
+  <h2>Fastest route</h2>
+  <ul class="points">
+    <li>{{FASTEST_ROUTE}}</li>
+  </ul>
+
+  <footer>Written locally by codecall. The planted bug was removed with Git before this receipt was written. Nothing was uploaded.</footer>
+</main>
+</body>
+</html>

package/plugins/codecall/skills/codecall/references/drill.md

@@ -0,0 +1,116 @@
+# Drill: debugging practice on real code
+
+A drill is a debugging interview round run on the developer's own project.
+Plant one bug, hand over only the symptom, coach without solving, then put the
+code back exactly as it was. Drills are the only codecall mode that edits
+source code, so every rule below about Git and restoring is mandatory.
+
+## Start gate
+
+1. Check Git: `git rev-parse --is-inside-work-tree` must succeed and
+   `git status --porcelain` must print nothing outside `codecall/`, where
+   earlier receipts live. Otherwise stop and ask the developer to commit or
+   stash first; never commit, stash, branch or reset on their behalf. Record
+   `git rev-parse HEAD`.
+2. Pick the target: the area named in the argument, else the implementation
+   from this conversation, else ask for one line. Read progressively, as in
+   the Session: the named files first, then focused excerpts. Never scan the
+   whole repository.
+3. Find how the developer will see the bug: an existing test, a run command,
+   a request (`curl`), or a script. Prefer an existing test that covers the
+   target. If nothing can show a symptom, pick another site or say so.
+4. Show this and wait:
+
+   ```text
+   Debugging drill: <area>
+   Difficulty: <easy|medium|hard>
+   Estimated time: <N> minutes
+   I will change one file to plant a bug and restore it with Git at the end.
+   If your editor asks you to approve that edit, approve it without reading it.
+
+   Start Drill / Skip
+   ```
+
+   On Skip or cancel: stop, and write nothing.
+
+## Plant the bug
+
+1. Choose one realistic bug, the kind people actually ship: an off-by-one, a
+   flipped comparison, a missing `await`, an unhandled null or empty case,
+   swapped arguments, a wrong status code, a stale or wrong cache key, a
+   mutable default, a missing transaction or lock, a wrong state update.
+   For server-side code, prefer a misconception from the matching card in
+   [backend-map/](backend-map/index.md), so the bug teaches a mapped concept;
+   remember its id. When earlier receipts' `codecall-concepts` meta tags show
+   a mapped id as missed and the target exercises it, prefer it.
+2. Match the difficulty:
+   - `easy`: it crashes, and the stack trace points near the bug.
+   - `medium`: wrong output, with the bug one call or layer away from where the
+     symptom shows.
+   - `hard`: wrong only for some inputs or timings, or fails silently; the
+     developer has to find the input that shows it.
+3. Constraints: one file, at most three changed lines, compiles or parses,
+   and looks like plausible code, not like a planted bug. No comment, name or
+   formatting change gives it away. Never plant a bug in auth or permission
+   checks, secrets, migrations, data deletion, generated files, lockfiles or
+   CI config, and never make a change that is unsafe if it runs against a
+   shared service.
+4. Make the edit, then run the reproduction once yourself to confirm the
+   symptom appears. If it does not, restore and pick a different bug.
+5. Record the time (`date +%s`). From here, never name the file, function,
+   line or kind of bug in chat until the reveal.
+
+## Run the drill
+
+1. Hand over a symptom report, as an interviewer would: what users see, what
+   was expected, and the reproduction command. Nothing else.
+2. The developer drives. Answer questions the way an interviewer would: say
+   what the system does, but never where the bug is. Let them run commands,
+   add logs and set breakpoints themselves.
+3. Hints only when asked, one at a time, in this order:
+   1. The area or layer to look in.
+   2. What to log, print or break on, and what to compare.
+   3. The function.
+   4. The line.
+   Count every hint given.
+4. The drill ends when the developer names the line and why it causes the
+   symptom (found), gives up, or asks to stop (missed). A fix they write is
+   welcome but not required; the code is restored either way.
+
+## Reveal and restore
+
+1. Show `git diff`: the planted change and what it should have been.
+2. Explain the causal chain from that line to the symptom in two or three
+   steps, then the fastest route a strong candidate would take: reproduce,
+   read the error in full, narrow down with logs or breakpoints, state a
+   hypothesis, confirm it.
+3. Restore: `git checkout -- <file>`. Then run `git status --porcelain`.
+   Anything still changed outside `codecall/` is the developer's own debugging
+   (logs, prints, a fix): list it and ask whether to revert it; revert only on
+   a yes. Confirm `git rev-parse HEAD` matches the recorded value; if it moved,
+   check `git diff <recorded> HEAD -- <file>` and tell the developer if the
+   bug was committed, without rewriting their history.
+4. Restore on every way out: found, missed, stop, error, or a new request
+   that abandons the drill. If restoring fails, stop and tell the developer
+   the exact command to run; never leave a drill bug in silently.
+
+## The drill receipt
+
+Write `./codecall/NNNN-drill-<slug>.html` from
+[drill-receipt-template.html](drill-receipt-template.html), numbered like
+every other receipt. Print the path and the result line in chat. It holds:
+
+- The area and the date.
+- Found or missed, the minutes taken, and the hints used out of 4.
+- The kind of bug in a few words, with the file name only; no source code.
+- What the developer did well and one habit to work on, both specific to
+  how this drill went, and the fastest route in one line.
+- For a missed drill whose bug maps to a concept card, one "Go deeper" line
+  with that card's links, exactly as written there.
+- Meta tags: `codecall-mode` is `drill`, `codecall-drill` is `found` or
+  `missed`, `codecall-hints` and `codecall-minutes` are numbers,
+  `codecall-concepts` is `id:ok` or `id:no` for the mapped concept, or empty.
+  `id:ok` means found with at most two hints.
+- When earlier receipts exist, the same streak line as a quiz receipt.
+
+Write the receipt only after the code is restored.

package/plugins/codecall/skills/codecall/references/receipt-template.html

@@ -3,9 +3,13 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<!-- Fill every double-brace placeholder and remove unused concept rows. Keep the two meta tags: later sessions read them for the streak line. -->
+<!-- Fill every double-brace placeholder and remove unused concept rows. Keep the four meta tags: later sessions read them for the streak line. -->
+<!-- "learn" for a quiz session, "trace" for a trace. -->
+<meta name="codecall-mode" content="{{MODE}}">
 <meta name="codecall-score" content="{{SCORE_N}}/{{SCORE_M}}">
 <meta name="codecall-date" content="{{DATE}}">
+<!-- Mapped concepts only, e.g. "cache-aside:ok,cache-invalidation:no"; leave content empty when nothing was mapped. -->
+<meta name="codecall-concepts" content="{{MAPPED_CONCEPTS_OR_EMPTY}}">
 <title>codecall · {{TITLE}}</title>
 <style>
   :root { --bg:#fbfaf7; --ink:#151515; --muted:#6b6760; --line:#e4e0d8; --ok:#1f7a4d; --no:#b3261e; --accent:#2b3e8c; }
@@ -28,6 +32,8 @@
   .concept b { display: block; }
   .concept span { color: var(--muted); font-size: 16px; }
   .points li::before { content: "→ "; color: var(--accent); }
+  .deeper { display: block; margin-top: 4px; font-size: 15px; color: var(--muted); }
+  .deeper a { color: var(--accent); }
   footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
   @media print { body { background: #fff; color: #000; } main { padding: 0; } }
 </style>
@@ -43,9 +49,9 @@
 
   <h2>What was in the change</h2>
   <ul>
-    <!-- One li per concept. Use class="ok" with ✅ or class="no" with ❌. -->
+    <!-- One li per concept. Use class="ok" with ✅ or class="no" with ❌. Only a ❌ concept with a map id keeps the deeper line, with its card's links (drop the second link when the card has one); delete it everywhere else. -->
     <li class="concept"><span class="ok">✅</span><div><b>{{CONCEPT_1}}</b><span>{{WHY_1}}</span></div></li>
-    <li class="concept"><span class="no">❌</span><div><b>{{CONCEPT_2}}</b><span>{{WHY_2}}</span></div></li>
+    <li class="concept"><span class="no">❌</span><div><b>{{CONCEPT_2}}</b><span>{{WHY_2}}</span><span class="deeper">Go deeper: <a href="{{LINK_1_URL}}">{{LINK_1_TEXT}}</a> · <a href="{{LINK_2_URL}}">{{LINK_2_TEXT}}</a></span></div></li>
   </ul>
 
   <h2>Points to remember</h2>

package/plugins/codecall/skills/codecall/references/trace.md

@@ -0,0 +1,42 @@
+# Trace: follow one flow through the code
+
+A trace walks one concrete path, such as "what happens on `POST /login`" or
+"where does this value get set", from its entry point to its end, then checks
+that the developer can follow it. It never edits code.
+
+## Start gate
+
+1. Identify the flow from the argument. If it is unclear, ask for one line
+   before reading any code.
+2. Find the entry point (route, handler, `main`, UI event, CLI command, job)
+   and read forward from it, one hop at a time. Read only the files on the
+   path; never scan the whole repository.
+3. Pick the 2 or 3 hops where a bug would most likely hide: where data is
+   transformed, validated, stored, cached, sent across a boundary, or can
+   fail. These are the session's ideas. For server-side hops, give each at
+   most one [backend map](backend-map/index.md) id, under the same rules as
+   the Session.
+4. Show the Start Learning / Skip card from the Start gate in SKILL.md, with
+   `Learning opportunity: trace <flow> through <N> files`. On Skip or cancel:
+   stop, and write nothing.
+
+## Session
+
+1. Walk the path hop by hop: `file:line`, what comes in, what it does, what
+   goes out, and how it can fail. Quote only the few lines that matter.
+2. End the walk with the path as one arrow chain, for example
+   `routes/auth.ts:login → AuthService.verify → users.findByEmail → bcrypt.compare → signJwt`.
+3. Check each chosen hop with one question, one at a time: a debugging or
+   failure question grounded in the path, such as "if `findByEmail` returns
+   nothing, what does the client get, and where is that decided?". Never a
+   generic definition.
+4. Branch as in the Session: correct moves on; wrong names the gap, reteaches
+   it from the path, and asks a new isomorphic question. A hop counts as
+   explained when its check was answered correctly without a reteach.
+
+## The receipt
+
+Write it from [receipt-template.html](receipt-template.html) like a quiz
+receipt, with `codecall-mode` set to `trace`, the flow as the title, each
+chosen hop as a concept, the arrow chain as the first point to remember, and
+the score as `Could explain N of M` hops.