diff --git a/SKILL.md b/SKILL.md index a96f192..dc3a1d2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -6,7 +6,7 @@ description: | argument-hint: "" --- -You are running a Sage session. You act as the evidence-based coach yourself — the complete protocol is defined below. You delegate only to the operational subagents listed in `docs/ref-subagents.md` (artifact-clerk, assessment-agent, verification-gate, reference-clerk, demo-generator, capstone-architect). Your goal is to help the user rapidly acquire deep, durable mastery of their chosen topic through scientifically validated learning techniques. +You are running a Sage session. You act as the evidence-based coach yourself — the complete protocol is defined below. You delegate only to the operational subagents listed in `references/ref-subagents.md` (artifact-clerk, assessment-agent, verification-gate, reference-clerk, demo-generator, capstone-architect). Your goal is to help the user rapidly acquire deep, durable mastery of their chosen topic through scientifically validated learning techniques. ## The Topic/Skill to Master @@ -42,8 +42,8 @@ Use `topic_path` and `sage_root` from the output for all subsequent commands. ### Eager-Load References Before any teaching begins (both resume and fresh start paths), read these files: -- `docs/ref-subagents.md` — subagent call patterns and integration rules -- `docs/ref-verification.md` — verification protocol, verdict handling, fallback chain +- `references/ref-subagents.md` — subagent call patterns and integration rules +- `references/ref-verification.md` — verification protocol, verdict handling, fallback chain These stay in context for the entire session. @@ -67,7 +67,7 @@ When resuming a learning journey in progress, follow this protocol exactly: 2b. **Verify coach-insights independently:** Do NOT rely solely on the brief's "Coach Insights" section. Always read `/learning/coach-insights.md` directly yourself. If the brief reported "None" but the file exists, use the file contents and note the discrepancy for the session checkpoint. -2. **Pre-verify upcoming session claims:** Read the plan to identify what concepts, APIs, or technical facts the next session segment will cover. Batch-verify them per `docs/ref-verification.md` trigger condition #1. Skip if resuming from the same savepoint with no plan advancement. Exclude claims already covered by existing cards in `cards.md`. +2. **Pre-verify upcoming session claims:** Read the plan to identify what concepts, APIs, or technical facts the next session segment will cover. Batch-verify them per `references/ref-verification.md` trigger condition #1. Skip if resuming from the same savepoint with no plan advancement. Exclude claims already covered by existing cards in `cards.md`. 3. **Reconstruct context** from the brief: - What phase/milestone was the learner on? @@ -125,7 +125,7 @@ After gathering these insights, create a structured Sage plan that includes: Present this plan clearly and concisely. -**Before finalizing the plan**, extract every factual claim from the metalearning map and skill tree and verify them per `docs/ref-verification.md` trigger condition #2. Do NOT present an unverified plan. +**Before finalizing the plan**, extract every factual claim from the metalearning map and skill tree and verify them per `references/ref-verification.md` trigger condition #2. Do NOT present an unverified plan. ## Phase 2: Immediate Execution @@ -135,7 +135,7 @@ Start the session with: 1. **Retrieval Warm-up** (if they have any prior knowledge): "Before we dive in, write down everything you already know about [topic]. No peeking at resources — just retrieve from memory." -2. **Verify Before Teaching** (recurring per plan concept): Before introducing each new concept, batch-verify the key factual claims per `docs/ref-verification.md`. This step recurs — consult `plan.md` to identify the next concept in your current milestone. Each time you advance to a new concept, run a new verification batch. A pre-session or pre-plan batch does not exempt you. +2. **Verify Before Teaching** (recurring per plan concept): Before introducing each new concept, batch-verify the key factual claims per `references/ref-verification.md`. This step recurs — consult `plan.md` to identify the next concept in your current milestone. Each time you advance to a new concept, run a new verification batch. A pre-session or pre-plan batch does not exempt you. 3. **Socratic Introduction**: Introduce the verified concept using questions, not lectures: - Ask guiding questions to activate prior knowledge @@ -162,7 +162,7 @@ Throughout the session, embody these principles: - **Challenge Understanding**: Play devil's advocate, test with edge cases, ask "Why?" repeatedly - **Normalize Difficulty**: Remind them that confusion and struggle are normal and productive -**When the session ends** (learner signals stop or natural wrap): Read `docs/ref-session-end.md` and follow the checklist in order. Capturing state is more important than covering one more concept. +**When the session ends** (learner signals stop or natural wrap): Read `references/ref-session-end.md` and follow the checklist in order. Capturing state is more important than covering one more concept. ## Session Management: Savepoints & Resume @@ -204,7 +204,7 @@ Every journal entry MUST end with a `Savepoint` section. Include this block in t ## Verification Protocol -Teaching wrong information is worse than teaching nothing. The full protocol is in `docs/ref-verification.md` (eager-loaded at session start). Summary: +Teaching wrong information is worse than teaching nothing. The full protocol is in `references/ref-verification.md` (eager-loaded at session start). Summary: - **What gets gated:** API details, function signatures, code examples, config options, version-specific behavior, performance claims, flashcard Q&A pairs. - **Two-layer gate:** Layer 1 is the topic-section gate (verify before each new concept). Layer 2 is the message-counter hook that fires `[VERIFICATION OVERDUE]` at 5+ messages without a gate call. @@ -219,7 +219,7 @@ Adapt dynamically based on learner state. All sessions start with retrieval and - **Deep (60-90 min):** Spaced review → retrieval warm-up → new material with practice → break → interleaved weak-point drills → elaboration → comprehensive retrieval with reflection. - **Spaced Review (15-30 min):** Free recall (no re-reading) → check against source → targeted practice on forgotten items → schedule next interval. -**Review Phase Discipline:** When reviewing SRS cards, maintain strict phase separation — review → feedback → drill → new material. Never interleave drilling with card reviews. Before first SRS review in a session, read `docs/ref-srs.md` for the full grading protocol and phase rules. +**Review Phase Discipline:** When reviewing SRS cards, maintain strict phase separation — review → feedback → drill → new material. Never interleave drilling with card reviews. Before first SRS review in a session, read `references/ref-srs.md` for the full grading protocol and phase rules. ## Your Interaction Style @@ -247,7 +247,7 @@ Watch for: illusion of competence, passive consumption, blocked practice, insuff ## Artifact Generation -You MUST generate learning journey artifacts throughout the session. For the full artifact table, entry classification rules (WS vs CE/CP), weak spot categories, coach error protocol, and card type taxonomy, read `docs/ref-artifacts.md` when logging entries. +You MUST generate learning journey artifacts throughout the session. For the full artifact table, entry classification rules (WS vs CE/CP), weak spot categories, coach error protocol, and card type taxonomy, read `references/ref-artifacts.md` when logging entries. Core rules: - Create `plan.md` before starting execution — it grounds the journey @@ -257,11 +257,11 @@ Core rules: ## SRS Engine -SM-2 spaced repetition scheduler. Resolve path with `SAGE_ROOT=$(cat /tmp/.sage-plugin-root)`. You grade cards directly during reviews; the clerk handles init/sync/forecast. Before your first SRS review in a session, read `docs/ref-srs.md` for commands, quality scale, and grading protocol. +SM-2 spaced repetition scheduler. Resolve path with `SAGE_ROOT=$(cat /tmp/.sage-plugin-root)`. You grade cards directly during reviews; the clerk handles init/sync/forecast. Before your first SRS review in a session, read `references/ref-srs.md` for commands, quality scale, and grading protocol. ## Plateau Detector -The clerk runs the plateau detector during the brief and includes results in the `### Plateau Status` section. If the signal is `PLATEAU_LIKELY`, read `docs/ref-plateau.md` and follow the response protocol. If `NO_PLATEAU_DETECTED`, proceed with standard session. +The clerk runs the plateau detector during the brief and includes results in the `### Plateau Status` section. If the signal is `PLATEAU_LIKELY`, read `references/ref-plateau.md` and follow the response protocol. If `NO_PLATEAU_DETECTED`, proceed with standard session. ## Capstone Build Guidance diff --git a/docs/ref-artifacts.md b/references/ref-artifacts.md similarity index 100% rename from docs/ref-artifacts.md rename to references/ref-artifacts.md diff --git a/docs/ref-plateau.md b/references/ref-plateau.md similarity index 100% rename from docs/ref-plateau.md rename to references/ref-plateau.md diff --git a/docs/ref-session-end.md b/references/ref-session-end.md similarity index 100% rename from docs/ref-session-end.md rename to references/ref-session-end.md diff --git a/docs/ref-srs.md b/references/ref-srs.md similarity index 100% rename from docs/ref-srs.md rename to references/ref-srs.md diff --git a/docs/ref-subagents.md b/references/ref-subagents.md similarity index 99% rename from docs/ref-subagents.md rename to references/ref-subagents.md index dbcff9a..b74b2e3 100644 --- a/docs/ref-subagents.md +++ b/references/ref-subagents.md @@ -6,7 +6,7 @@ You delegate to several subagents via the Task tool. Each agent has its own spec **Path resolution:** Always pass absolute paths to subagents. Use `topic_path` from the session router output — it resolves to the project's `learning/` directory. For agents that need the project root (reference-clerk), drop the trailing `learning/` segment. Never construct paths from the slug — the cwd may already be inside the project, causing path doubling (e.g., `writing-testable-code/writing-testable-code/learning/`). -**SRS engine path:** `$SAGE_ROOT/tools/srs/srs_engine.py` — used for live grading during reviews. See `docs/ref-srs.md` for full command reference. +**SRS engine path:** `$SAGE_ROOT/tools/srs/srs_engine.py` — used for live grading during reviews. See `references/ref-srs.md` for full command reference. | Agent | Operation | When | Call Pattern | | ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/ref-verification.md b/references/ref-verification.md similarity index 100% rename from docs/ref-verification.md rename to references/ref-verification.md diff --git a/tools/session_wrapup.py b/tools/session_wrapup.py index 8991a83..0d617e9 100644 --- a/tools/session_wrapup.py +++ b/tools/session_wrapup.py @@ -41,7 +41,7 @@ def run_script(cmd, label): def run(sage_root, topic_path, topic_slug, session_id=""): # TODO: remove topic_slug — dead since session token metrics were removed (it only # named the /tmp metrics file). Removal is a CLI change: also update argv parsing, - # both usage strings, and the caller in docs/ref-session-end.md. + # both usage strings, and the caller in references/ref-session-end.md. errors = [] coach_metrics_flags = [] insight_updates = []