Pitch Generator Lab Helper Skill

The Lab Helper skill provides an interactive, pedagogical diagnosis and recovery engine for learners working through the Pitch Generator lab (bwg001-devlab-1b). It actively inspects the learner's workspace directory against the 9 reference solution steps across Modules 1–4, assesses syntactic and structural drift, delivers calibrated educational guidance, and safely restores files if a learner gets stuck.

Conversational & Prompt-Driven Interaction

The learner interacts with this skill entirely through natural conversation in the Antigravity chat panel. The learner does not need to run terminal verification commands or remember CLI flags.

1. Handling Learner Inquiries (Strictly On-Demand)

Important: Only invoke this skill on-demand when the learner explicitly asks to verify a step, requests a hint, or asks for help fixing a stuck step. Never run verification or read .agents/solutions/ while implementing a normal feature prompt.

When the learner sends prompts such as:

• "I can't get step 2a working properly, can you give me a hint?"
• "Please verify I completed step 1a correctly"
• "Can I have another hint?"
• "I am completely stuck on step 3c, please help me fix it"

The assistant follows this multi-step protocol:

1. Step Identification: Identify the module and step referenced in the user's prompt (for example, step 2a maps to Module 2, Step 2a). If the user asks generally ("verify step 2"), inspect the workspace to identify the active step.
2. Contextual Tier Tracking: Inspect the recent conversation history to determine which hint tier to provide:
   • First inquiry on a step (e.g., "give me a hint" or "verify step 1a"): Use Tier 1 (Conceptual Nudge).
   • Follow-up request (e.g., "can I have another hint?" or "need more detail"): Advance to Tier 2 (Targeted File & Symbol Hint).
   • Second follow-up (e.g., "still stuck, another hint?"): Advance to Tier 3 (Implementation Blueprint & Code Snippet).
   • Exhausted hints or explicit remediation request (e.g., "please bring my workspace into a working state"): Use In-Place Remediation to patch the step into pitch_generator/.
3. Execute Diagnostic & Semantic Intent Comparison:
   • Run the verification script using run_command:

     python3 .agents/skills/lab-helper/scripts/verify_workspace.py --module <M> --step <S> --tier <T> --json

   • Semantic Intent Allowance: If verify_workspace.py reports a missing helper symbol, compare the learner's code in pitch_generator/ against the corresponding .agents/solutions/ reference file. If the learner's code achieves the same architectural intent and runtime behavior (with only benign differences in local variable names, helper function names, or instruction phrasing), treat the step as completed and congratulate the learner!
4. Interpret Output & Formulate Response:
   • If completed (drift_detected: false or semantically equivalent): Congratulate the learner, confirm that their implementation meets the step's architectural goal, and briefly summarize what they accomplished.
   • If substantive drift is detected: Present the progressive hint corresponding to the current tier (see TEMPLATES.md). Explain the architectural rationale ("why") and encourage the learner to iterate.
   • If Remediation is requested: Read the reference file in .agents/solutions/ and surgically patch pitch_generator/ in-place at the corresponding # [Guidepost — Step <id>] block. Never overwrite cumulative files (pitch_generator/agent.py or pitch_generator/app_utils/services.py) wholesale, so earlier steps, user customizations, and remaining guidepost comments for future steps are preserved.

Progressive 3-Tier Hint & In-Place Remediation Protocol

To ensure learners build genuine understanding without having solutions spoiled prematurely, Lab Helper enforces a deterministic 3-tier progressive hint protocol:

1. Tier 1 — Conceptual Nudge:
   • Offers an architectural "why" explanation and high-level conceptual nudge.
   • Highlights the core design pattern (for example, ADK single-responsibility agents, JoinNode fan-in, PreToolUse policy hooks).
   • Strictly read-only: does not disclose specific file paths, code snippets, or modify workspace files.
2. Tier 2 — Targeted File & Symbol Hint:
   • Identifies the exact target file path relative to the workspace root.
   • Details required classes, functions, AST symbols, interface signatures, or schema keys.
   • Highlights missing tokens without writing code or modifying learner files.
3. Tier 3 — Concrete Implementation Blueprint:
   • Delivers a concrete implementation blueprint and minimal idiomatic code snippet illustrating how to resolve the drift.
   • Explains parameter bindings, edge cases, and verification commands.
   • Strictly read-only: does not overwrite any learner files.
4. In-Place Surgical Remediation:
   • Used when hints are exhausted or the learner explicitly asks to fix/restore a step.
   • For cumulative files (pitch_generator/agent.py, pitch_generator/app_utils/services.py, pitch_generator/fast_api_app.py), read the reference solution in .agents/solutions/ and patch the missing/broken step code in-place, preserving all prior steps and future # [Guidepost — ...] comments.
   • For standalone files (pitch_generator/skills/brand-guidelines/SKILL.md, pitch_generator/sql/*.sql), restore or create the file from .agents/solutions/.

Supported Modules and Steps (1a–4a)

Lab Helper supports all 9 progressive steps across the 4 syllabus modules:

Running the Workspace Verification Script

The underlying diagnostic engine is implemented in scripts/verify_workspace.py and executed by the assistant via CLI commands:

1. Requesting Progressive Hints (Read-Only)

# Tier 1 Conceptual Nudge
python3 .agents/skills/lab-helper/scripts/verify_workspace.py --module 1 --step 1a --tier 1 --json

# Tier 2 Targeted File & Symbol Hint
python3 .agents/skills/lab-helper/scripts/verify_workspace.py --module 1 --step 1a --tier 2 --json

# Tier 3 Implementation Blueprint
python3 .agents/skills/lab-helper/scripts/verify_workspace.py --module 1 --step 1a --tier 3 --json

2. Auto-Remediating a Stuck Step

# Restore step files to bring workspace to 0 drift
python3 .agents/skills/lab-helper/scripts/verify_workspace.py --module 1 --step 1a --tier remediate --json

3. Inspecting the Entire Workspace

# Verify all steps across all 4 modules
python3 .agents/skills/lab-helper/scripts/verify_workspace.py --step all --json

Reference Documentation

• See REFERENCE.md for the detailed step rubrics, AST symbols, CLI flags, exit codes, and JSON response schema.
• See TEMPLATES.md for the standardized educator response formatting templates for Tiers 1–3 and auto-remediation.
• Structured hint data and drift rules are maintained in references/hints_catalog.json and consumed by scripts/verify_workspace.py.