jjliu6

---
name: ai-usage-audit
author: Junjie Liu / Philosophie AI
version: 1.0.0
description: Monthly AI usage retrospective and insights — pulls your recent conversation history, analyzes usage patterns across multiple dimensions, and generates a polished HTML report with an actionable improvement checklist. Trigger when the user says "AI usage audit", "usage review", "review my chats", "monthly retrospective", "analyze my conversations", "how have I been using AI", "月度回顾", "使用审计", "AI 使用回顾". Also trigger when the user wants to understand their AI usage efficiency, discover inefficiency patterns, or optimize human-AI collaboration. Even casual phrases like "what have I been doing lately" (referring to AI conversations) or "let's do a retro" should trigger this skill. Note: this skill requires an AI product with memory or chat history features (e.g. Claude Pro with memory).
---

# AI Usage Audit — Monthly Retrospective & Insights

## Purpose

Turn your AI conversation history into a mirror: see what you're actually using AI for, where you're efficient, where you're wasting time, and where collaboration friction is highest. It's essentially a Sprint Retro applied to human-AI collaboration — a data-driven approach to continuously improving how you work with AI.

## When to Trigger

- User says "AI usage audit", "usage review", "monthly retrospective", "review my chats"
- User says "analyze my conversations", "how have I been using AI"
- User says "月度回顾", "使用审计", "AI 使用回顾", "分析我的对话"
- User wants to understand their AI usage efficiency or patterns
- User says "what have I been doing lately" or "let's do a retro" (referring to AI conversations)

## Prerequisites

This skill depends on `recent_chats` and `conversation_search` tools to pull conversation history. If these tools are unavailable, inform the user that this skill only works with AI products that have conversation history features.

## Language Configuration

**Default**: Match the user's language (detect from their message).

If the user specifies a language preference (e.g. "in English", "用中文", "en français"), use that language for the entire report. The HTML report, all analysis text, section headers, and the improvement checklist should all be in the chosen language.

Technical terms, tool names, and conversation titles may remain in their original language regardless of the report language.

## Data Collection Phase

Thorough data collection is the foundation of analysis quality. Don't start writing after pulling just one page — the more comprehensive the data, the more valuable the insights.

### Step 1: Determine Analysis Window

Default: past 30 days. If the user specifies a different time range, follow their request.

Calculate the time window: today minus 30 days (or the user-specified number of days) to get the `after` parameter.

### Step 2: Pull Conversation Records

Use `recent_chats` tool multiple times, n=20 each time, paginate with the `before` parameter until the entire time window is covered or approximately 5 rounds have been pulled.

For each conversation, record:
- Conversation title/topic (inferred from chat snippet)
- Update timestamp
- Approximate content category (for later analysis)

If the user is inside a Project, only conversations within that Project will be retrieved; if outside a Project, only non-Project conversations are available. Inform the user of this scope limitation.

### Step 3: Supplementary Search (Optional)

If high-frequency topics from recent_chats need more context, use `conversation_search` with relevant keywords to dig deeper.

## Analysis Framework

Analyze collected conversation data across five dimensions. Every dimension must be backed by specific evidence (conversation titles or content references) — no abstract conclusions without support.

### Dimension 1: Theme Clustering — "What am I using AI for?"

Categorize all conversations by topic. Typical categories include but are not limited to:
- Content creation (writing, copywriting, translation)
- Programming & technical (code, debugging, architecture)
- Research & learning (concept exploration, information synthesis)
- Decision-making & analysis (strategy, comparison, evaluation)
- File processing (documents, spreadsheets, presentations)
- Casual & exploratory (conversations without clear goals)

Output the conversation count and percentage for each category. Identify the "center of gravity" — the 2-3 areas where time and energy are most concentrated.

### Dimension 2: Pattern Detection — "Are there inefficiency patterns?"

Look for these signals:
- **Repeated questions**: Same or similar questions appearing across different conversations (knowledge not being retained)
- **Abandoned threads**: Tasks started but never completed (unclear goals or priority confusion)
- **Over-exploration**: Circling the same topic without converging on action (information consumption, not production)
- **Tool mismatch**: Using AI for things that could be solved faster with other tools
- **Context rebuilding**: Repeatedly providing background because conversations weren't continued in the same thread

For each identified pattern, provide specific conversations as evidence.

### Dimension 3: Value Output — "Which conversations actually produced something?"

Distinguish two types of conversations:
- **High-value output**: Produced concrete, usable deliverables (documents, code, presentations), made decisions, formed actionable plans
- **Low-efficiency consumption**: Primarily information intake, not converted into action or output

Estimate the proportion of high-value output conversations. Consumption isn't inherently bad — the goal is to make the ratio visible so the user can judge whether it's healthy.

### Dimension 4: Collaboration Friction — "Where does human-AI collaboration break down?"

Look for these friction signals:
- **Excessive revision**: Same output revised 3+ times (initial requirements were unclear)
- **Clarification loops**: Extensive back-and-forth to clarify what the user actually wants
- **Wrong tool choice**: Used an inappropriate tool or approach, then switched
- **Expectation gap**: User expressed dissatisfaction or started a new conversation for the same task

For each friction point, analyze root cause: was it a user-side issue (unclear requirements, unrealistic expectations) or an AI-side limitation (capability boundary, tool limitation)?

### Dimension 5: Highlights — "When was collaboration at its best?"

Identify 2-3 "best practice" moments:
- Conversations with the highest collaboration efficiency
- Conversations with the best output quality
- Most creative uses of AI

Analyze what these highlights have in common — under what conditions does collaboration work best?

## Output: HTML Report

Generate a polished HTML file, save to `/mnt/user-data/outputs/` and present with `present_files`.

### Report Structure

```
┌──────────────────────────────────────────────┐
│  HEADER                                       │
│  - "AI Usage Audit" + time range              │
│  - Total conversations / coverage / date       │
│  - One-sentence summary (overall profile)      │
└──────────────────────────────────────────────┘

§1  Data Overview
    - Total conversation count, time distribution (which days/weeks most active)
    - Topic distribution bar (pure CSS, no JS chart libraries)
    - Top keywords from the period

§2  Theme Clustering Analysis
    - Each category with conversation count and representative conversations
    - "Center of gravity" analysis
    - 🔍 Insight: Does your AI usage align with your core goals?

§3  Patterns & Efficiency
    - Identified inefficiency patterns (each with specific evidence)
    - Efficiency visualization using "traffic light" notation:
      🟢 Efficient / 🟡 Optimizable / 🔴 Needs change
    - 💡 Improvement suggestions (per pattern)

§4  Value Output Assessment
    - High-value vs. low-efficiency consumption ratio
    - Representative high-value conversations (brief description of output)
    - 📊 ROI assessment: time invested vs. actual output

§5  Collaboration Friction Points
    - Friction type statistics
    - Top 3 friction scenarios with root cause analysis
    - 🔧 Solutions (specific improvement methods per friction point)

§6  Highlights & Best Practices
    - 2-3 highlight moments
    - Common traits behind these highlights
    - ✨ Practices worth replicating

§7  Next Month Improvement Checklist
    - Based on all analysis above, generate 3-5 specific, actionable improvements
    - Each item format: What to do + Why + How to measure
    - Presented in checkbox style for easy tracking
    - This is the most important actionable section — no empty platitudes

§8  One-Paragraph Summary
    - 2-3 sentences for overall closure
    - Tone: like a coach who knows your work giving a monthly debrief
    - Not a repetition of prior sections — distill one core insight
```

### Section Usage Principles

- **Always write**: §1, §2, §3, §7, §8 (core skeleton)
- **Recommended**: §4, §6 (most audits will have content for these)
- **As needed**: §5 (only when clear friction is found)
- If data is too sparse (fewer than 10 conversations), switch to a compact version: §1 + §3 + §7 + §8

## Visual Design

The HTML report follows a clean, modern editorial design:

### Overall Style
- Light background (#faf9f6 warm white), high readability
- Serif font for headings (Newsreader), sans-serif for body (Inter for English, Noto Sans SC for Chinese, or appropriate font for other languages)
- Maximum width 820px, centered layout
- Comfortable spacing with breathing room between sections

### Key Components
- **Data cards**: White background, rounded corners, key numbers
- **Proportion bars**: Pure CSS horizontal bars for topic distribution
- **Traffic light labels**: 🟢🟡🔴 + text descriptions
- **Insight boxes**: Colored left border + light background (blue=insight, green=highlight, orange=suggestion, red=warning)
- **Checklist cards**: Checkbox-styled cards, each item actionable
- **Conversation references**: Gray background quote blocks with conversation title and timestamp

### Color System
- Each theme cluster category gets a distinct color (from a fixed palette)
- High-value = green tones, low-efficiency = orange tones, friction = red tones, highlights = blue tones

### Google Fonts
```html
<link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,wght@0,400;0,600;0,700;1,400&family=Inter:wght@300;400;500;600;700&family=Noto+Sans+SC:wght@300;400;500;600;700&display=swap" rel="stylesheet">
```

## Writing Style

### Tone
- Like a personal coach giving a monthly debrief — someone who knows your work
- Warm but not sentimental, data-driven but not cold
- Direct about problems but not judgmental — the goal is improvement, not evaluation
- Humor is fine; flippancy is not

### Format
- Use prose, not lists (except for the Checklist section)
- Use color highlights for key insights
- Every analysis point backed by evidence (conversation references)
- Summary paragraphs limited to 2-3 sentences — no rambling

### Language
- Write in the language determined by the Language Configuration section
- Tool names and technical terms stay in English regardless
- Conversation titles quoted as-is in their original language

## Quality Checklist

Before delivery, verify:
- [ ] Pulled enough conversation records (at least 3 pagination rounds or full time window)?
- [ ] Theme clustering backed by concrete data (not gut-feel categorization)?
- [ ] Each inefficiency pattern supported by specific conversations as evidence?
- [ ] Improvement checklist specific enough ("what + why + how to measure" all present)?
- [ ] One-paragraph summary distills a core insight (not repeating prior sections)?
- [ ] HTML report saved to outputs directory and presented with present_files?
- [ ] If fewer than 10 conversations, switched to compact version?

## What This Skill is NOT

- ❌ Not a token consumption tracker (doesn't count specific token usage)
- ❌ Not a full transcript dump (doesn't list every conversation verbatim)
- ❌ Not an AI product review (doesn't evaluate the AI's capabilities)
- ❌ Not a privacy audit (doesn't analyze sensitive information exposure)
- ✅ It's a personal retrospective to help you **see how you use AI and continuously improve your workflow**

## Credits

Built by **Junjie Liu / Philosophie AI**

- GitHub: [github.com/jjliu6](https://github.com/jjliu6)
- LinkedIn: [linkedin.com/in/junjieliu](https://linkedin.com/in/junjieliu/)
- Website: [philosophie.ai](https://philosophie.ai)

Part of the [ClawHub](https://github.com/jjliu6) skill collection.

FILE:README.md
# 🔍 AI Usage Audit — Monthly Retrospective & Insights

> Sprint Retro for your AI collaboration. Turn your conversation history into a mirror.

## What is this?

A [ClawHub Skill](https://github.com/jjliu6) that analyzes your past month of AI conversations and generates a polished HTML report with actionable insights.

**Think of it as a personal coach reviewing your AI usage patterns** — what you're spending time on, where you're inefficient, where collaboration breaks down, and what to improve next month.

## The Problem

You use AI every day. But do you use it *well*?

Most people have no idea:
- How much time goes to **real output** vs. **passive info consumption**
- Which conversations are **repeated** (same question, different day)
- Where the **human-AI friction** is (unclear prompts → endless revisions)
- Whether their AI usage **aligns with their actual priorities**

This skill turns your chat history into data-driven self-awareness.

## What It Analyzes

| Dimension | What It Looks For |
|-----------|-------------------|
| **Theme Clustering** | What topics dominate? Does your AI usage match your goals? |
| **Pattern Detection** | Repeated questions, abandoned threads, info-consumption loops |
| **Value Output** | Which conversations produced real deliverables vs. just browsing? |
| **Collaboration Friction** | Where does the human-AI loop break down? Root cause analysis |
| **Highlights** | Your best AI collaboration moments — what made them work? |

## Output

A polished HTML report including:

- 📊 Data overview with topic distribution
- 🔍 Inefficiency patterns with evidence
- 📈 Value output assessment
- 🔧 Friction point analysis with root causes
- ✅ **Next month's improvement checklist** (actionable, measurable)
- 💬 One-paragraph coaching summary

## Language Support

The report **auto-detects your language** from your message. You can also explicitly request any language:

- `Run a usage audit` → English report
- `帮我做一次 AI 使用回顾` → Chinese report
- `Fais un audit de mon utilisation` → French report

## How to Use

### Option 1: Install as ClawHub Skill

Download `ai-usage-audit.skill` and install it in your Claude environment.

Then simply say:
```
Run a monthly AI usage audit
```

### Option 2: Use the Prompt Directly

Copy the prompt below into any AI product that has **chat history / memory** features:

<details>
<summary>📋 Click to expand the full prompt</summary>

```
Please run an "AI Usage Retrospective & Insights" analysis:

1. Pull my recent conversations (as many as possible from the past month, paginate through multiple pages)

2. Analyze across these dimensions:
   * Theme clustering: What have I mainly been doing? How is my time distributed?
   * Pattern detection: Any recurring workflows, repeated questions, or abandoned conversations?
   * Value assessment: Which conversations produced high-value results (files, decisions, code)? Which were low-efficiency info consumption?
   * Friction points: Where did my collaboration with AI break down? (e.g. excessive revisions, unclear requirements, wrong tool choices)
   * Recommendations: Based on the above, give me 3-5 specific, actionable improvements (what to do + why + how to measure)

3. Output format: concise prose (not bullet lists), highlight key insights with color, end with a one-paragraph summary.
```

</details>

### Requirements

⚠️ **This only works with AI products that have chat history / memory features.** Examples:
- Claude Pro / Team / Enterprise (with memory enabled)
- Any AI product with conversation history APIs

## Why Monthly?

Like any retrospective, the value compounds over time. Monthly cadence is ideal because:
- **Weekly** is too noisy — not enough data to spot patterns
- **Quarterly** is too late — bad habits have already calcified
- **Monthly** hits the sweet spot — enough data, fast enough feedback loop

## License

MIT — use it, fork it, improve it.

## Author

Built by [Junjie Eric Liu](https://linkedin.com/in/junjieliu/) as part of the [ClawHub](https://github.com/jjliu6) skill collection.

---

*If you find this useful, consider giving it a ⭐ — it helps others discover it.*

---
name: github-repo-teardown
metadata:
  author: Junjie Liu / Philosophie AI
  homepage: https://www.linkedin.com/in/junjieliu/
  version: 1.0.0
description: >
  Deep-dive teardown of any GitHub open-source project into a beautifully designed HTML report
  that both product people and engineers can understand. Covers architecture, design decisions,
  comparable repos, and actionable application scenarios. Use this skill whenever the user shares
  a GitHub repo URL and asks to analyze, explain, teardown, or understand a project. Also trigger
  when the user says things like "break down this repo", "how does this project work", "analyze
  this codebase", "walk me through this repo", "what can I learn from this project", "explain
  this open-source project", "拆解一下", "帮我看看这个项目", or "讲解这个 repo". Even if the user
  just drops a GitHub link with a brief "what is this?" — use this skill. Produces a polished
  HTML teardown document covering product logic, technical architecture, and practical takeaways.
---

# GitHub Repo Teardown

## Purpose

Transform any GitHub open-source project into a **product + engineering teardown** — a single
HTML document that explains not just *what* the code does, but *why* it's designed that way
and *what you can learn from it*. The core premise: every technical choice reflects a product
judgment, and every product design requires an architecture to support it.

## When to Trigger

- User shares a GitHub repo URL and asks to analyze / explain / teardown
- User says "break down this repo", "how is this designed", "analyze this project"
- User mentions "teardown", "code walkthrough", "explain this codebase"
- User wants to learn from an open-source project's design
- User drops a GitHub link with even minimal context ("what is this?")

## Configuration

### Language

Output defaults to **English**. If the user's message is in another language (e.g., Chinese,
Japanese, Spanish), match that language for the narrative while keeping technical terms,
code references, and file paths in their original form.

If the user explicitly requests a language (e.g., "write it in Chinese", "用中文写"),
follow that instruction regardless of the default.

## Research Phase

Before writing anything, gather comprehensive information. Follow these steps in order,
spending 5-15 tool calls depending on repo complexity. **Do not skip steps — thin research
produces thin teardowns.**

### Step 1: Repo Overview

- `web_fetch` the GitHub repo main page to get: README content, directory structure,
  stars/forks/language breakdown, license, last commit date
- Pay attention to any Architecture / Design / How It Works sections in the README
- Check for `ARCHITECTURE.md`, `DESIGN.md`, `CONTRIBUTING.md`, or `AGENTS.md`

### Step 2: Deep-Dive Sources (pick 2-4 most useful)

- `web_search` "{repo-name} architecture" or "{repo-name} how it works internally"
- Try fetching DeepWiki: `https://deepwiki.com/{owner}/{repo}` — often has good architecture
  analysis. If unavailable, skip without concern — it's a nice-to-have, not a dependency.
- Look for the project's official blog post, launch announcement, or HN/Reddit discussion
- If the repo has a `/docs` directory or documentation site, fetch key pages

### Step 3: Source Code Reconnaissance

- From README and any architecture docs, identify 3-5 **key source files** — entry points,
  core modules, config files, data models
- `web_fetch` these files directly via raw GitHub URLs:
  `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}`
- You don't need to read every line — focus on understanding the **relationships between
  files**, the **main abstractions**, and any **clever patterns**
- Check `package.json`, `Cargo.toml`, `pyproject.toml`, or equivalent for dependency insights

### Step 4: Community & Traction Signals

- Scan the Issues tab (sort by most commented or most reacted) to understand:
  - What problems users actually hit
  - What features are most requested
  - Where the project's limitations show
- Check Discussions or recent release notes if available
- Note contributor count and commit frequency — signals project health

### Step 5: Comparable Repos Discovery (CRITICAL — do not skip)

This step directly feeds CH.6 and is one of the highest-value parts of the teardown.

- `web_search` for 2-4 comparable or alternative projects:
  - "{repo-name} vs" or "{repo-name} alternatives"
  - Search by the problem domain: "{problem-the-repo-solves} open source"
- For each comparable repo found, `web_fetch` its GitHub page to get: stars, language,
  approach/architecture, key differentiator
- Look for projects that solve the **same problem differently**, not just forks or clones
- Note: "comparable" includes both direct competitors AND projects with similar architectural
  patterns applied to different domains

### Step 6: Synthesize Before Writing

Before opening any file, mentally organize:
- **One-line definition** of what this project is (test: would a smart non-technical person get it?)
- **The main analogy** you'll use throughout the document
- **3 key design decisions** that make this project interesting
- **The "aha" insight** — what's the non-obvious thing about this project?

## Output Framework

Produce a single HTML file saved to `/mnt/user-data/outputs/` and displayed via `present_files`.

### Document Structure (10 chapters — trim as needed)

```
┌─────────────────────────────────────────────────┐
│  HEADER                                          │
│  - Project name + one-line definition (must fit  │
│    in a single sentence)                         │
│  - Health indicators: Stars / Language / Version  │
│  - Audience tag: who should read this            │
└─────────────────────────────────────────────────┘

CH.1  What Problem Does It Solve?
      - Before vs After (pain → solution)
      - A real-world analogy (non-technical readers should get it)
      - 🔑 Product Insight (why this problem is worth solving)

CH.2  Core Mechanism
      - Explain the core working principle using ONE main analogy
        that runs through the entire document
      - Side-by-side: what the user sees vs what the system does
      - ⚙️ Technical Notes (file names, function names for deep-divers)

CH.3  Architecture & Key Decisions
      - Architecture flow diagram (annotated with the analogy)
      - "Why A not B" decision cards (3-5 key design choices)
      - 🎯 Product-level takeaway for each decision

CH.4  A Single Operation's Full Journey
      - Pick ONE typical user action and trace it through the system
      - Timeline-style: each step shows what happens + what tech is used
      - Technical notes: file paths, function names

CH.5  Product Design Highlights (3-5)
      - Each highlight: Title + Paragraph + Product Insight
      - Tag which ones are "reusable patterns"

CH.6  Comparable Repos & Positioning
      - 2-4 comparable/alternative projects with actual GitHub links
      - For each: what it is, stars, approach, key difference
      - Positioning matrix or comparison table
      - "When to use THIS repo vs THAT repo" decision guide
      - (If insufficient data found in research, say so honestly
        and provide what you have)

CH.7  Risks & Trade-offs
      - 2-3 key limitations or trade-offs
      - "What did it sacrifice to gain its current advantage?"
      - Honest > comprehensive

CH.8  Technical Quick Reference
      - Source tree with annotations
      - Tech stack table
      - Key dependencies explained
      - (Reference section for deep-divers)

CH.9  Where Can This Be Applied? (Application Brainstorm)
      - Three tiers of application (see detailed spec below)
      - Card-based layout, each scenario as an independent block
      - Distinguish "use directly" vs "borrow the pattern"
      - 6-8 cards total (quality over quantity)

CH.10 Portable Takeaways
      - 3-5 transferable insights from this project
      - Numbered, 1-2 sentences each
      - Not a summary — distill into reusable mental models
```

### CH.6 Comparable Repos — Detailed Spec

This chapter is one of the most valuable parts of the teardown. Users want to understand
not just what THIS project does, but how it fits in the landscape.

**Required elements:**
- Each comparable repo gets: Name (linked), Stars count, Language, One-line description,
  Architectural approach, Key differentiator from the subject repo
- A clear "when to use which" decision framework
- Honest assessment — don't artificially favor the subject repo

**Comparison formats (pick the most appropriate):**
- **Table**: Best for 3+ repos with clear feature dimensions
- **Decision tree**: Best when the choice depends on context ("If you need X, use A; if Y, use B")
- **Positioning map**: Best when repos differ on 2 clear axes

**If research yielded thin results:**
- State clearly: "Limited comparable projects found in this specific niche"
- Still provide whatever alternatives exist, even if they're partial overlaps
- Suggest search terms the reader can use to find more

### CH.9 Application Scenarios — Detailed Spec

The most practically valuable chapter. Goal: give readers **specific, actionable** directions,
not vague possibilities.

#### Three Tiers

**Tier A: Use Directly — "What can I do with it tomorrow?"**
- What real problem can this repo solve as-is?
- 2-3 specific scenarios: Who uses it / For what / Expected outcome
- Format: "A [role] can use this to [specific action], eliminating [specific pain point]"

**Tier B: Combine — "What creates a chemical reaction?"**
- What tools/platforms/products does this pair well with for 1+1>2 effects?
- 2-3 combination proposals, each explaining what NEW capability emerges
- Focus on **non-obvious combinations** — obvious ones are already in the README

**Tier C: Borrow the Pattern — "What new products could this inspire?"**
- Extract the core design pattern (not the code) and apply it elsewhere
- Use the format: "If you apply [this pattern] to [another domain], you get..."
- 2-3 cross-domain applications, each specific enough to be a product spec
- This is the most creative tier — encourage bold leaps, but each must land
  on a concrete product form

#### Card Design

Each scenario is an **independent card** with:
- Type tag: 🔧 Use Directly / 🧪 Combine / 💡 Borrow Pattern
- Scenario title
- One-line summary: who + what for
- 2-3 sentences on how to execute

Total: 6-8 cards. Every card must contain genuine insight.

### Chapter Usage Rules

- **Must write**: CH.1, CH.2, CH.3, CH.4, CH.9, CH.10 (core skeleton)
- **Strongly recommended**: CH.5, CH.6, CH.8 (applicable to most repos)
- **Write if warranted**: CH.7 (when there are clear trade-offs)
- Overall principle: **every paragraph must add information — no padding**
- If a chapter would be thin, skip it entirely rather than write filler

## Writing Style Guide

### The Throughline Analogy

- Choose **1 main analogy** per project (e.g., browser-use = "a remote-controlled restaurant order")
- Introduce it in CH.1, extend it through CH.2-CH.4
- The analogy must serve understanding, not decoration
- Avoid: switching to a new unrelated analogy every chapter

### Dual-Layer Narrative

- **Surface layer**: Product logic, business value, user perspective
  (a PM can read just this layer and understand 80%)
- **Deep layer**: File paths, function names, protocol details
  (engineers dig into this layer for implementation specifics)
- Visually separate them: technical details use `code font`, gray backgrounds,
  or "Technical Note" callout boxes

### Insight Callouts

Use colored callout boxes to mark insights:
- 🔵 Blue: Product insight / Design principle
- 🟠 Orange: Technical design lesson
- 🟢 Green: Reusable pattern
- 🟣 Purple: Growth / Business strategy

### Voice & Tone

- Like a senior product advisor giving you a **private briefing**
- Not a textbook, not a blog post — it's "help you understand fast and form judgment"
- Opinions are welcome but labeled: distinguish analysis from fact
- Concise and direct — every sentence earns its place

### Language Conventions

- Narrative in the configured output language (default: English)
- Technical terms stay in English regardless (Daemon, IPC, CDP, Schema, etc.)
- Code snippets and file paths always in original form
- Project-specific terminology in original language with brief explanation on first use

## Visual Design Guide

### Overall Aesthetic

- Light background (#faf9f6 warm white), high readability
- Serif font for headings (Newsreader) — gravitas
- Sans-serif for body (Inter) — modern readability
- Monospace for technical content (JetBrains Mono)
- Max width 820px, centered layout
- Generous whitespace, clear visual hierarchy

### Google Fonts

```html
<link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,wght@0,400;0,600;0,700;1,400&family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">
```

### Key Components

- **Analogy cards**: White rounded cards, 💡 emoji marker
- **Comparison panels**: Two-column layout (Before vs After, Traditional vs New)
- **Flow diagrams**: Horizontal emoji flow with arrow connectors
- **Decision cards**: 2×2 grid, Q&A format
- **Insight callouts**: Left color bar + tinted background
- **Timeline**: Circle dots + vertical line + content cards
- **Tech reference**: Monospace file tree + tables
- **Scenario cards**: Independent rounded cards, type tag top-left (🔧/🧪/💡)
- **Comparable repo cards**: GitHub-style cards with stars badge, language dot, link

### Responsive Design

- Cards stack vertically on narrow screens
- Side-by-side comparisons collapse to stacked on mobile
- Font sizes adjust for readability

## Quality Checklist

Before delivering, verify:

- [ ] One-line definition is truly one sentence?
- [ ] Main analogy runs through the entire document (not switching per chapter)?
- [ ] Every chapter adds new information (not rephrasing earlier content)?
- [ ] A PM can understand 80% reading only the surface layer?
- [ ] An engineer can find specific files and functions in the deep layer?
- [ ] CH.6 includes actual GitHub links to comparable repos?
- [ ] CH.6 has a clear "when to use which" decision guide?
- [ ] CH.9 scenarios are specific enough (who / what / how all stated)?
- [ ] CH.9 "Borrow Pattern" tier has genuine cross-domain leaps (not "same domain, new name")?
- [ ] CH.10 takeaways are transferable mental models (not a project summary)?
- [ ] Insights are specific to THIS project (not "AI is changing the world" platitudes)?
- [ ] HTML saved to `/mnt/user-data/outputs/` and displayed via `present_files`?

## What This Skill is NOT

- ❌ Not a code review (doesn't read every line)
- ❌ Not a README translation (doesn't repeat existing docs)
- ❌ Not an academic paper (doesn't aim for completeness)
- ❌ Not an SEO article (no filler content)
- ✅ It's a **product teardown** that helps you rapidly understand a project's design wisdom
  and walk away with actionable insights

---

## Credits

Built by **Junjie Liu** at [Philosophie AI](https://philosophie.ai) — where AI proves its
value through real, practical use.

- GitHub: [github.com/jjliu6](https://github.com/jjliu6)
- LinkedIn: [linkedin.com/in/junjieliu](https://linkedin.com/in/junjieliu)
- Products: [philosophie.ai](https://philosophie.ai)

If this skill helped you understand a project better, consider starring it on ClawHub.