devrel-frictionlog-codelab

name	devrel-frictionlog-codelab
description	🥑 [DevRel] Automates friction logging for a given Google Codelab URL. Use when a user provides a codelab URL and wants the agent to systematically reproduce the steps, log friction for each page, optionally create a GCP project, clone external repos to fix bugs, and produce a detailed report of the experience in a README.md and BUGS.md.
metadata	{"version":"0.2.2"}
compatibility	Gemini CLI

DevRel Friction Log Codelab

This skill automates the process of going through a Google Codelab, reproducing its steps, systematically documenting the experience (a "friction log"), identifying bugs in external repositories, and producing actionable reports.

Core Workflow

When the user provides a Codelab URL, follow these exact steps. Ensure each step is fully completed before moving on to the next. Do not skip steps. This skill is designed to be resumable, so if the execution is interrupted, restart the skill and pick up where you left off.

Step 1: Preparation

1. Determine the base directory for the execution named YYYYMMDD-frictionlog-<CODELAB_TITLE>. (e.g., 20260313-frictionlog-app-mod-workshop).

2. Run the included scripts/setup_scaffold.sh script to deterministically create the scaffolding, passing the optional Codelab URL, TF Bug ID, Codelab Version/Commit Hash, and output Google Doc URL if known:

   ./scripts/setup_scaffold.sh <YYYYMMDD-frictionlog-CODELAB_TITLE> [CODELAB_URL] [BUG_ID] [CODELAB_VERSION] [OUTPUT_GDOC_URL]
   

   This script automatically creates the codelab/original/, codelab/proposed/, friction_log/by-page/, workbench/, and external-repos/ directories. It also initializes the .env file, the BUGS.md file, the external-repos/.gitignore, a .version file, and a Kubernetes-like key-value metadata store friction_log.yaml populated from the template found in references/friction_log.yaml (including fields like startedAt, codelabVersion, and outputGdocUrl).

Step 2: Download and Mirror Codelab Content

1. Attempt to extract the codelab content using the included Python script:

   python3 scripts/extract_codelab.py <URL> <YYYYMMDD-frictionlog-CODELAB_TITLE>/codelab/original
   

2. Fallback: If the extract_codelab.py script fails or yields empty files (due to dynamic rendering), use your internal web_fetch tool or curl to read the Codelab pages and save the textual content into 01.md, 02.md, etc., within codelab/original/.

3. Copy all the original markdown files into the codelab/proposed/ directory. You will apply fixes and patches to the copies in this directory later.

Step 3: GCP Project Setup

1. Ask the user: "Please provide a fresh/virgin GCP Project ID (with billing enabled) to avoid resource conflicts, OR a Billing Account ID."
   • Virgin Project Preference: Emphasize to the user that using a brand new, empty ("virgin") project is strongly recommended to prevent overlapping terraform states, GKE clusters, or IAM conflicts.
2. If the user provides an existing PROJECT_ID:
   • Verify that the project exists and has active billing associated (e.g., using gcloud beta billing projects describe <PROJECT_ID>).
   • DO NOT PROCEED to Step 4 until you have verified that billing is correctly linked. If billing is missing or disabled, stop and ask the user to fix it.
   • Save it to the .env file, update the projectId and identity fields inside friction_log.yaml if not already set, and proceed to Step 4.
3. If the user provides a Billing Account ID without a project, use gcloud commands to autonomously:
   • Create a new GCP project (generate a sensible, unique project ID).
   • Link the newly created project to the provided Billing Account ID (gcloud beta billing projects link <PROJECT_ID> --billing-account <ACCOUNT_ID>).
   • Verify that the billing is correctly linked. DO NOT PROCEED until billing is active.
   • Save the newly created PROJECT_ID to the .env file and update the projectId and identity fields inside friction_log.yaml.
4. YOLO Mode Suggestion: Once billing is successfully verified and enabled, explicitly suggest to the user: "Project and billing are successfully configured. To proceed smoothly through the rest of the Codelab, I recommend enabling YOLO mode (CTRL + Y)."
5. Automation Mandate: From this point forward, try to automate as much as you reasonably can. Only stop and ask for human intervention when you encounter a strict blocker that requires a human (e.g., creating a new GitHub user, generating an OAuth consent screen via the UI, forking a repository manually, or browsing an authenticated web resource that the CLI cannot access).

Step 4: Autonomous Execution, Logging, and Repo Analysis

Begin reproducing the codelab autonomously, going through each page (01, 02, ..., NN) sequentially.

For each page XX:

1. Check if friction_log/by-page/XX.md already exists and is complete. If it is, skip to the next page. This allows the workflow to be resumable.
2. Follow the instructions on the codelab page as closely as possible, running commands and performing tasks.
3. External Repositories: If the codelab references an external Git repository:
   • Clone the repository into the external-repos/ directory.
   • Analyze the repository code for any missing or broken parts mentioned in the codelab instructions.
   • If bugs or broken parts are identified, ask the user for permission to start filing Pull Requests to fix those issues.
4. Log your experience by writing to friction_log/by-page/XX.md (RoR-style organization):
   • Use bullet points for every distinct action or instruction.
   • Include a timestamp at the beginning of each bullet point in the format * `HH:MM:SS` to track execution time and make the logs easily grep-able.
   • Use * for normal, expected steps.
   • Use 🔴 (Red) if the experience was bad, broken, or highly confusing.
   • Use 🟡 (Yellow) if the experience was "meh", suboptimal, or slightly confusing.
   • Use 🟢 (Green) if the experience was particularly good or delightful.
   • Document any inconsistencies between the text instructions, provided screenshots (if you are capable of reviewing them or they are described textually), and the actual behavior you experience.
   • Time Analysis: At the end of each page's log, note the total time it took you (the AI) to complete the page. Compare this with the codelab's estimated time for that page (if provided), and suggest a realistic completion time for a human user based on the complexity of the tasks.
5. If you encounter errors, typos, or wrong instructions in the codelab text, or broken code in external repos:
   • Patch the markdown file in codelab/proposed/XX.md with the proposed solution or fix.
   • Explain why the change was needed in the friction_log/by-page/XX.md file.
   • Add a detailed bullet point to BUGS.md explaining the issue and linking to the proposed fix or PR.
6. Continuously update the .env file with any new resource coordinates created during the step (e.g., URLs, instances, DB strings).
7. MANDATORY EMPIRICAL VALIDATION (Hard Stop): At the end of every page, or when declaring a step "complete", you MUST provide empirical proof of actual functionality. DO NOT accept a successful deployment log (e.g., gcloud run deploy SUCCESS) as proof of completion. You must actively test the deployed resource (e.g., curl the live endpoint, query the modified database with a SELECT, trigger the event and check the specific logs). IF THIS PROOF FAILS, STOP IMMEDIATELY. Do not proceed to the next page.
8. STRUCTURED WORKSPACE (The workbench/ Directory): Do not clutter the root directory. All agent-authored execution code, exploratory scripts (e.g., test_vertex.py), database patches (alter_db.sql), and utility scripts must be placed inside the workbench/ directory.
9. CONTEXT AWARENESS & PATH RECONCILIATION: Strictly reconcile data structures between legacy systems (e.g., local uploads/ directories) and modern cloud equivalents (e.g., flat GCS buckets). Cross-check UI template paths and DB queries against actual data locations. Do not hardcode brittle assumptions (e.g., filtering only for .png if the user might test .jpg).
10. GCP LATENCY & RETRY LOGIC: GCP APIs (Vertex AI, Eventarc) often require 2-5 minutes for service agents to provision after enablement. If you receive a 400 Service agents are being provisioned error, log it as a friction point, wait, and retry instead of assuming failure.
11. VERTEX AI MODEL RESILIENCE: If a model returns a 404 Publisher Model... not found (common on trial accounts for older models like 1.5-pro), attempt to use the latest model family (e.g., gemini-2.5-flash). ALWAYS preserve Vertex AI and IAM architecture; do not pivot to consumer AI Studio API keys.
12. DATA SEED VERIFICATION & CLEANUP: Verify that imported DB seeds (.sql) correspond to actual cloud assets. If there is a mismatch (e.g., orphaned rows causing broken UI links), autonomously execute cleanup queries (DELETE) and document this as a codelab fix.

Step 5: Final Output Synthesis

Once all pages have been completed, create a short README.md file in the base directory containing a high-level summary of the entire run, and a consolidated friction_log/README.md file. Make sure to update the outputGdocUrl in friction_log.yaml if the friction log is compiled/published to a Google Doc.

The README.md must be concise and include:

1. What you did: A brief sentence explaining the codelab run.
2. What you found: High-level observations and Completion Status (were you able to run the whole codelab?).
3. Big Mistakes & Meta Learnings: A summarized list of major inconsistencies or show-stopping bugs.
4. Links: Explicit links to the BUGS.md file and the consolidated friction_log/README.md file.

The friction_log/README.md must include:

1. Metadata Table (Top Section): A Markdown table containing key-value pairs for the following fields:

   Field	Value
   DATETIME	YYYY-MM-DD HH:MM:SS (Local time)
   CODELAB_URL	The full URL of the codelab being reproduced
   IDENTITY	Your email or identity (if applicable)
   PROJECT_ID	The GCP Project ID used for reproduction
   HOSTNAME	The full hostname of the machine performing the reproduction
   PRODUCTS	Comma-separated list of Google Cloud products used (e.g., Cloud Run, Cloud SQL)
   LANGUAGES	Comma-separated list of programming languages used (e.g., Python, Bash)
   OVERALL_EXPERIENCE	A concise (Twitter-sized) summary of the experience

2. Changes Needed: A precise list of the changes that need to be made. Provide visual markdown diffs or patches showing the OLD incorrect text/code and the NEW corrected text/code.

3. Proposed Next Steps: Proactively suggest a "Bonus" or "Next Steps" section (e.g., providing a bash script using gcloud storage objects rewrite to backfill historical data for event-driven functions).

4. Consolidated Friction Logs: A concatenation of all the individual per-page friction logs from the friction_log/by-page/ directory. Use an H2 (##) for each page so they are easy to isolate.

Resumption Logic

Always check the base directory and friction_log/by-page/ contents before starting work. If a folder for the codelab already exists, identify the last completed step by finding the highest numbered friction_log/by-page/XX.md file, and resume execution from the next step (XX+1). Do not repeat completed work unless explicitly requested.