GhostScientist avatar

documentation-skills

Skills for generating architectural documentation and wikis with source code traceability

GitHub stars
5

Install

/plugin install documentation-skills@GhostScientist-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add GhostScientist/skills.

Contents

Discovered from source

Skills 10

Create watchOS Version

Analyzes existing Apple platform projects and creates detailed, phased implementation plans for watchOS apps that are elegant, top-tier experiences—not naive skins of the parent app.

Workflow

  1. Project Discovery - Analyze project structure, patterns, architecture
  2. Feature Mapping - Identify watchOS-suitable features and priorities
  3. API Compatibility - Search web for current watchOS API availability
  4. Architecture Planning - Design watchOS-specific architecture
  5. Plan Generation - Create phased plan with warnings and alternatives
  6. User Review - Present plan for approval before implementation

Phase 1: Project Discovery

Run the bundled analyzer first — it reports architecture, dependencies, existing targets, and watchOS-incompatible frameworks as JSON:

python3 scripts/analyze_project.py <project_path>

Use its watchos_incompatible list to seed Phase 3. If the script fails or the project layout is unusual, fall back to scanning manually for:

├── App Architecture (SwiftUI, UIKit, AppKit, hybrid)
├── Data Layer (Core Data, SwiftData, Realm, custom)
├── Networking (URLSession, Alamofire, custom)
├── State Management (ObservableObject, TCA, Redux-like)
├── Navigation (NavigationStack, Coordinator)
├── Shared Frameworks (SPM packages, shared targets)
├── Assets (colors, images, SF Symbols)
├── Existing Watch Target (if any)
└── Minimum iOS Version (affects watchOS targeting)

Key files: *.xcodeproj, Package.swift, Info.plist, App entry points, ViewModels, Models.

Phase 2: Feature Mapping

Glanceable (High Priority): Status displays, counters, progress, recent items, quick stats

Quick Actions (High Priority): Single-tap toggles, shortcuts, haptic confirmations

Complications/Widgets (Critical): Map data to WidgetKit families—accessoryCircular, accessoryRectangular, accessoryInline, accessoryCorner. Consider Smart Stack relevance.

Background: HealthKit integration, background refresh, Watch Connectivity sync

Defer/Exclude: Complex data entry, long-form content, sustained screen time features

Phase 3: API Compatibility

CRITICAL: Always search web for current watchOS docs before finalizing. APIs change frequently.

Search: [FrameworkName] watchOS availability site:developer.apple.com

Quick Reference

Available: SwiftUI, SwiftData (10+), WidgetKit (9+), HealthKit, WorkoutKit, CoreLocation (limited), WatchConnectivity, CloudKit, CoreMotion, AVFoundation (audio), CoreBluetooth, Combine, Swift Concurrency

Unavailable/Limited: UIKit, WebKit, MapKit (limited), CoreImage (limited), ARKit, RealityKit, StoreKit (limited), Background URLSession (limited)

See references/api-compatibility.md for detailed compatibility matrix.

Phase 4: Architecture

Version Targeting

Each iOS release has a paired watchOS release. Derive the target from the project's existing minimum iOS version rather than assuming the latest:

iOS 16+ → watchOS 9+  (WidgetKit complications)
iOS 17+ → watchOS 10+ (SwiftData, Smart Stack)
iOS 18+ → watchOS 11+ (Live Activities on Watch)

This mapping is a starting point, not an authority — newer OS versions ship every year. Confirm the current pairing and any newer capabilities on developer.apple.com before committing to a deployment target.

Structure

Shared/
├── Models/           # Pure Swift, shared via target membership
├── Services/         # Platform-agnostic logic
└── Utilities/

WatchApp/
├── App.swift
├── Views/
├── ViewModels/
├── Complications/
└── WatchConnectivity/

Design Principles

  1. Glanceability - Visible within 2 seconds
  2. Minimal Interaction - 1-3 taps max
  3. Context Awareness - Time, location, activity
  4. Battery Conscious - Efficient refresh, TimelineSchedule
  5. Haptic Feedback - Confirm actions appropriately

SwiftUI Gotchas

  • Avoid nested TabViews (memory leaks)
  • Use TimelineSchedule for efficient metric updates
  • Check isLuminanceReduced to reduce work when dimmed
  • Don't use data-driven high-frequency UI refreshes

Phase 5: Plan Generation

Use template in references/plan-template.md to generate:

  1. Executive Summary
  2. ⚠️ API Compatibility Warnings table
  3. Phased implementation tasks
  4. Testing checklist

Phase 6: User Review

Present plan and ask for approval before implementing:

"I've analyzed your project and created a watchOS plan. Before proceeding:

  1. API Warnings: [N] APIs unavailable—alternatives documented.
  2. Recommended Features: [list] prioritized for Watch.
  3. Scope: [N] phases.

Proceed with implementation, or adjust the plan?"

Do not implement until user approves.

Best Practices Reference

Watch Connectivity

guard WCSession.default.activationState == .activated else { return }
// sendMessage: immediate, requires reachability
// transferUserInfo: queued, guaranteed
// transferCurrentComplicationUserInfo: complication priority

Complications

// Use appropriate reload policy
Timeline(entries: entries, policy: .after(nextUpdateDate))
// Use .never for static complications

Battery Efficiency

  • Timeline-based over active refresh
  • Check isLuminanceReduced
  • Batch Watch Connectivity transfers
  • Significant location change vs continuous updates

Experiment Design Checklist

Prevent the "I ran experiments for 3 months and they're meaningless" disaster through rigorous upfront design.

The Core Principle

Before running ANY experiment, you should be able to answer:

  1. What specific claim will this experiment support or refute?
  2. What would convince a skeptical reviewer?
  3. What could go wrong that would invalidate the results?

Process

Step 1: State the Hypothesis Precisely

Convert your research question into falsifiable predictions:

Template:

If [intervention/method], then [measurable outcome], because [mechanism].

Examples:

  • "If we add auxiliary contrastive loss, then downstream task accuracy increases by >2%, because representations become more separable."
  • "If we use learned positional encodings, then performance on sequences >4096 tokens improves, because the model can extrapolate beyond training length."

Null hypothesis: What does "no effect" look like? This is what you're trying to reject.

Step 2: Identify Variables

Independent Variables (what you manipulate):

VariableLevelsRationale
[Var 1][Level A, B, C][Why these levels]

Dependent Variables (what you measure):

MetricHow MeasuredWhy This Metric
[Metric 1][Procedure][Justification]

Control Variables (what you hold constant):

VariableFixed ValueWhy Fixed
[Var 1][Value][Prevents confound X]

Step 3: Choose Baselines

Every experiment needs comparisons. No result is meaningful in isolation.

Baseline Hierarchy:

  1. Random/Trivial Baseline

    • What does random chance achieve?
    • Sanity check that the task isn't trivial
  2. Simple Baseline

    • Simplest reasonable approach
    • Often embarrassingly effective
  3. Standard Baseline

    • Well-known method from literature
    • Apples-to-apples comparison
  4. State-of-the-Art Baseline

    • Current best published result
    • Only if you're claiming SOTA
  5. Ablated Self

    • Your method minus key components
    • Shows each component contributes

For each baseline, document:

  • Source (paper, implementation)
  • Hyperparameters used
  • Whether you re-ran or used reported numbers
  • Any modifications made

Step 4: Design Ablations

Ablations answer: "Is each component necessary?"

Ablation Template:

VariantWhat's Removed/ChangedExpected EffectIf No Effect...
Full ModelNothingBest performance-
w/o Component ARemove APerformance drops X%A isn't helping
w/o Component BRemove BPerformance drops Y%B isn't helping
Component A onlyOnly A, no BShows A's isolated contribution-

Good ablations are:

  • Surgical (one change at a time)
  • Interpretable (clear what was changed)
  • Informative (result tells you something)

Step 5: Address Confounds

Things that could explain your results OTHER than your hypothesis:

Common Confounds:

ConfoundHow to CheckHow to Control
Hyperparameter tuning advantageSame tuning budget for allReport tuning procedure
Compute advantageMatched FLOPs/paramsReport compute used
Data leakageCheck train/test overlapStrict separation
Random seed luckMultiple seedsReport variance
Implementation bugs (baseline)Verify baseline numbersUse official implementations
Cherry-picked examplesRandom or systematic selectionPre-register selection criteria

Step 6: Statistical Rigor

Sample Size:

  • How many random seeds? (Minimum: 3, better: 5+)
  • How many data splits? (If applicable)
  • Power analysis: Can you detect expected effect size?

What to Report:

  • Mean ± standard deviation (or standard error)
  • Confidence intervals where appropriate
  • Statistical significance tests if claiming "better"

Appropriate Tests:

ComparisonTestAssumptions
Two methods, normal datat-testNormality, equal variance
Two methods, unknown distMann-Whitney UOrdinal data
Multiple methodsANOVA + post-hocNormality
Multiple methods, unknownKruskal-WallisOrdinal data
Paired comparisonsWilcoxon signed-rankSame test instances

Avoid:

  • p-hacking (running until significant)
  • Multiple comparison problems (Bonferroni correct)
  • Reporting only favorable metrics

Step 7: Compute Budget

Before running, estimate:

ComponentEstimateNotes
Single training runX GPU-hours[Details]
Hyperparameter searchY runs × X hours[Search strategy]
BaselinesZ runs × W hours[Which baselines]
AblationsN variants × X hours[Which ablations]
SeedsM seeds × above[How many seeds]
TotalT GPU-hoursBuffer: 1.5-2x

Go/No-Go Decision: Is this feasible with available resources?

Step 8: Pre-Registration (Optional but Recommended)

Write down BEFORE running:

  • Exact hypotheses
  • Primary metrics (not chosen post-hoc)
  • Analysis plan
  • What would constitute "success"

This prevents unconscious goal-post moving.

Output: Experiment Design Document

# Experiment Design: [Title]

## Hypothesis
[Precise statement]

## Variables
### Independent
[Table]

### Dependent
[Table]

### Controls
[Table]

## Baselines
1. [Baseline 1]: [Source, details]
2. [Baseline 2]: [Source, details]

## Ablations
[Table]

## Confound Mitigation
[Table]

## Statistical Plan
- Seeds: [N]
- Tests: [Which tests for which comparisons]
- Significance threshold: [α level]

## Compute Budget
[Table with total estimate]

## Success Criteria
- Primary: [What must be true]
- Secondary: [Nice to have]

## Timeline
- Phase 1: [What, when]
- Phase 2: [What, when]

## Known Risks
1. [Risk 1]: [Mitigation]
2. [Risk 2]: [Mitigation]

Red Flags in Experiment Design

🚩 "We'll figure out the metrics later" 🚩 "One run should be enough" 🚩 "We don't need baselines, it's obviously better" 🚩 "Let's just see what happens" 🚩 "We can always run more if it's not significant" 🚩 No compute estimate before starting 🚩 Vague success criteria

Hugging Face Space Deployer

Create, configure, and deploy interactive ML demos on Hugging Face Spaces.

Deployment fails in predictable ways when the model's type is misidentified. Always analyze the model before generating any code.

Workflow

  1. Analyze the model — full model, LoRA adapter, or Inference API supported.
  2. Choose a deployment strategy from that analysis.
  3. Ask the user if the model type or cost preference is unclear.
  4. Deploy with scripts/deploy_model.py, or assemble the Space manually.
  5. Set the runtime hardware in Space Settings.
  6. Verify the Space builds and actually answers a request.

Step 1: Analyze the model

Inspect the model's files on the Hub before anything else:

hf download username/model-name --local-dir /tmp/check --dry-run 2>&1 | grep -E '\.(safetensors|bin|json)'
Does it have adapter_config.json?
├── YES → LoRA adapter. Read base_model_name_or_path from that file.
│         Deploy with peft + ZeroGPU.
└── NO
    ├── Has model.safetensors / pytorch_model.bin?
    │   ├── Inference widget on the model page? → Inference API, cpu-basic
    │   └── No widget?                          → ZeroGPU, load with transformers
    └── Neither → incomplete upload. Ask the user.

Read references/model-analysis.md for the full file-to-type table, Inference API detection signals, the hardware tier table, and how to fix a missing pipeline_tag.

Adapters never have direct Inference API support. If you find adapter_config.json, the Inference API path is ruled out — do not attempt it.

Step 2: Deploy

scripts/deploy_model.py performs the analysis in Step 1 automatically and picks the strategy, hardware, and dependencies. Prefer it:

# Full model or Inference API model — strategy auto-detected
python scripts/deploy_model.py meta-llama/Llama-3-8B-Instruct --type chat

# LoRA adapter — base model read from adapter_config.json
python scripts/deploy_model.py username/my-lora-adapter --type chat

# Override the auto-detected base model
python scripts/deploy_model.py username/my-lora --type chat --base-model Qwen/Qwen2.5-Coder-1.5B-Instruct

--type is required and accepts chat, image-classification, text-to-image, text-generation, or embedding. Also available: --name, --hardware, --private, --org, and --force-zerogpu.

Requires huggingface_hub and an authenticated hf CLI (hf auth login).

To assemble a Space by hand instead — no network access to run the script, an unsupported model type, or the user asks to see the files — read references/manual-deployment.md. It maps each situation to the right starting files in assets/ and covers the placeholders to replace.

Step 3: Set hardware

GPU templates do not work until hardware is set manually. Go to https://huggingface.co/spaces/USERNAME/SPACE_NAME/settings → "Space Hardware" and select ZeroGPU (free, on-demand) or a paid tier. suggested_hardware in the README is only a hint.

This single step causes the most post-deploy failures, including the common "No API found" error.

Step 4: Verify

Watch the build logs, then send one real request. A Space can build cleanly and still fail at inference — a wrong LoRA base model produces garbage output rather than an error.

If anything fails, read references/troubleshooting.md.

Managing existing Spaces

scripts/manage_space.py handles hardware changes, secrets, and lifecycle:

python scripts/manage_space.py status username/my-space
python scripts/manage_space.py hardware username/my-space --tier t4-small
python scripts/manage_space.py secret username/my-space --key API_KEY --value xxx
python scripts/manage_space.py pause username/my-space      # stops billing
python scripts/manage_space.py restart username/my-space

scripts/create_space.py creates an empty, correctly-scaffolded Space when you want to upload files separately.

Gotchas

  • Use gradio>=5.0.0 and huggingface_hub>=0.26.0. Do not pin Gradio to an old exact patch version — gradio==4.44.0 raises ImportError: cannot import name 'HfFolder'.
  • Gradio 5.x requires nested lists for examples: [["ex1"], ["ex2"]], not ["ex1", "ex2"].
  • LoRA Spaces must include peft in requirements.txt.
  • Keep sdk_version in the README frontmatter consistent with the gradio version in requirements.txt.
  • Hardware pricing changes; point users to https://huggingface.co/docs/hub/spaces-gpus rather than quoting rates.

Bundled files

PathContents
scripts/deploy_model.pyAuto-detecting end-to-end deployment (preferred path)
scripts/create_space.pyCreate a scaffolded, empty Space
scripts/manage_space.pyHardware, secrets, pause/restart for existing Spaces
references/model-analysis.mdModel type detection, Inference API signals, hardware tiers
references/manual-deployment.mdHand-assembly walkthrough and template selection
references/troubleshooting.mdBuild and runtime error fixes
assets/Gradio/Streamlit app templates, requirements files, README templates

Implement Paper From Scratch

The best way to truly understand a paper is to implement it. This skill guides you through that process methodically.

Philosophy

  • No copy-pasting from reference implementations - We build understanding, not just working code
  • Checkpoint questions verify understanding - You should be able to answer "why" at each step
  • Minimal dependencies - Use NumPy/PyTorch fundamentals, not high-level wrappers
  • Deliberate debugging - Bugs are learning opportunities, not obstacles

Process

Phase 1: Pre-Implementation Analysis

Before writing any code:

  1. Identify the core algorithm - Strip away ablations, extensions, bells and whistles. What's the minimal version?

  2. List the components - Break into modules:

    • Data pipeline
    • Model architecture
    • Loss function(s)
    • Training loop
    • Evaluation metrics
  3. Find the tricky parts - What's non-obvious?

    • Custom layers or operations
    • Numerical stability concerns
    • Hyperparameter sensitivity
    • Implementation details buried in appendices
  4. Gather reference numbers - What should we expect?

    • Training loss trajectory
    • Validation metrics at convergence
    • Compute requirements (if stated)

Phase 2: Scaffolded Implementation

Build up the implementation in this order:

Step 1: Data
# Start with synthetic/toy data
# Verify shapes and types before touching real data

Checkpoint: Can you describe what each tensor represents and its expected shape?

Step 2: Model Architecture
# Build layer by layer
# Print shapes at each stage
# Verify parameter counts match paper

Checkpoint: If you randomly initialize and do a forward pass, do the output shapes match what the paper describes?

Step 3: Loss Function
# Implement exactly as described
# Test with known inputs/outputs
# Check gradient flow

Checkpoint: Can you explain each term in the loss and why it's there?

Step 4: Training Loop
# Minimal loop first (no logging, checkpointing, etc.)
# Verify loss decreases on tiny overfit test
# Then add bells and whistles

Checkpoint: Can you overfit a single batch? If not, something is broken.

Step 5: Evaluation
# Implement paper's exact metrics
# Compare against reported numbers

Checkpoint: On the same data split, how close are you to paper's numbers?

Phase 3: The Debugging Gauntlet

When it doesn't work (and it won't at first):

  1. The Overfit Test

    • Can you memorize 1 example? 10? 100?
    • If not, architecture or gradient bug
  2. The Gradient Check

    • Are gradients flowing to all parameters?
    • Any NaN or exploding gradients?
  3. The Initialization Check

    • Match paper's initialization exactly
    • This matters more than people think
  4. The Learning Rate Sweep

    • Log scale: 1e-5 to 1e-1
    • Loss should decrease for some range
  5. The Ablation Debug

    • Remove components until it works
    • Add back one at a time

Phase 4: Checkpoint Questions

At each stage, you should be able to answer:

Understanding:

  • Why does this component exist?
  • What would happen without it?
  • What alternatives were considered?

Implementation:

  • Why this specific implementation choice?
  • Where could numerical issues arise?
  • What's the computational complexity?

Debugging:

  • What would it look like if this was broken?
  • How would you test this in isolation?
  • What are the most likely bugs?

Output Format

For each implementation session, provide:

## Today's Implementation Goal
[Specific component we're building]

## Prerequisites Check
- [ ] Previous components working
- [ ] Understand what we're building
- [ ] Know expected behavior

## Implementation

### Code
[Code blocks with extensive comments]

### Checkpoint Questions
1. [Question]
   <details><summary>Answer</summary>[Answer]</details>

2. [Question]
   <details><summary>Answer</summary>[Answer]</details>

### Verification Steps
- [ ] Test 1: [What to check]
- [ ] Test 2: [What to check]

### Common Bugs at This Stage
1. [Bug pattern]: [How to identify and fix]

## What's Next
[Preview of next component and how it connects]

Tips for Specific Paper Types

Transformer-based

  • Attention mask shapes are the #1 bug source
  • Verify positional encoding is applied correctly
  • Check layer norm placement (pre vs post)

RL/Policy Gradient

  • Sign errors in policy gradient are silent killers
  • Advantage normalization matters
  • Verify discount factor handling

Generative Models

  • KL term balancing is finicky
  • Check latent space distribution
  • Verify reconstruction looks reasonable before training

Computer Vision

  • Normalization (ImageNet stats, batch norm) is crucial
  • Data augmentation can make or break results
  • Verify input preprocessing matches paper exactly

Success Criteria

You're done when:

  1. Numbers match - Within reasonable variance of paper's results
  2. Understanding is deep - You can explain every line of code
  3. You found the gotchas - You know what breaks and why
  4. You could modify it - Confident to try your own variations

Anti-Patterns to Avoid

  • ❌ Copying code you don't understand
  • ❌ Skipping checkpoint questions
  • ❌ Using pre-built components for core algorithm
  • ❌ Ignoring discrepancies with paper
  • ❌ Moving on before current step works

iOS App Icon Generator

Create beautiful, production-ready iOS app icons through a two-phase creative process.

Phase 1: Visual Philosophy

Before drawing anything, develop a 2-3 paragraph Icon Philosophy that articulates:

  • Core concept: What single idea or feeling should the icon convey?
  • Visual metaphor: What shape, object, or abstraction represents the app's purpose?
  • Color psychology: What palette evokes the right emotional response?
  • Silhouette test: Will it be recognizable as a tiny black shape?

Write this philosophy out. It guides every design decision.

Design Principles

Icons that work follow these rules:

  • Simplicity: One focal element. No more than 2-3 colors. No text (illegible at small sizes).
  • Distinctiveness: Must stand out in a grid of 30 other icons. Avoid generic symbols (gears, checkmarks, clouds).
  • Scalability: The 16x16 notification icon must read as clearly as the 1024x1024 App Store version.
  • No photography: Apple's guidelines discourage photos. Use illustration, geometry, or abstract forms.
  • Optical balance: Center of visual weight, not geometric center. Curves feel heavier than straight lines.

Phase 2: Icon Generation

Generate the icon as a self-contained HTML file with embedded SVG that:

  1. Renders the icon design at 1024x1024 (the master size)
  2. Includes iOS-style rounded corners (superellipse, not CSS border-radius)
  3. Shows a preview grid of all sizes to verify readability
  4. Provides a download mechanism for each size

Required Sizes

Generate all iOS app icon sizes:

SizePurpose
1024x1024App Store
180x180iPhone (@3x)
167x167iPad Pro (@2x)
152x152iPad (@2x)
120x120iPhone (@2x)
87x87Spotlight (@3x)
80x80Spotlight (@2x)
76x76iPad (@1x)
60x60iPhone (@1x)
58x58Settings (@2x)
40x40Spotlight (@1x)
29x29Settings (@1x)
20x20Notification (@1x)

HTML Artifact Structure

<!DOCTYPE html>
<html>
<head>
  <title>App Icon: [Name]</title>
  <style>
    /* Dark interface, icon grid layout, download buttons */
  </style>
</head>
<body>
  <!-- Philosophy statement -->
  <!-- Master SVG at 1024x1024 -->
  <!-- Preview grid showing all sizes -->
  <!-- Download buttons (use canvas to convert SVG → PNG) -->
  <script>
    // SVG → Canvas → PNG download logic
  </script>
</body>
</html>

SVG Guidelines

  • Use viewBox="0 0 1024 1024" for the master
  • Apply the iOS squircle mask (superellipse with n≈5)
  • Use gradients sparingly but effectively
  • Ensure googd stroke widths scale proportionally
  • Test: zoom browser to 25% - is the icon still clear?

iOS Squircle Mask

The iOS icon shape is NOT a rounded rectangle. Use this superellipse path or approximate with:

<clipPath id="ios-squircle">
  <path d="M512,1024 C252,1024 0,772 0,512 C0,252 252,0 512,0 C772,0 1024,252 1024,512 C1024,772 772,1024 512,1024 Z" />
</clipPath>

Or generate programmatically with the superellipse formula: |x/a|^n + |y/b|^n = 1 where n ≈ 5.

Process

  1. Ask about the app's purpose, name, and any existing brand colors
  2. Write the Icon Philosophy
  3. Describe 2-3 concept directions with rationale
  4. Get user approval on a direction
  5. Generate the HTML artifact with full icon set
  6. Iterate based on feedback

Quality Bar

The output should look like it belongs on a top-10 App Store chart. Every icon in that grid was crafted by a professional designer - yours should be indistinguishable from theirs.

Avoid:

  • Glossy/skeuomorphic styles (outdated since iOS 7)
  • Thin hairline details (disappear at small sizes)
  • Overly complex illustrations
  • Generic clip-art aesthetics
  • Centered-circle-on-gradient laziness

Paper to Intuition

Transform dense academic papers into genuine understanding through layered explanation and visual intuition.

Process

  1. Get the paper - Ask for the arXiv link, PDF, or paper title
  2. Extract the core - Identify the single key insight (one sentence)
  3. Build the ladder - Create explanations at 4 levels
  4. Visualize intuition - Generate interactive diagrams
  5. Stress test understanding - "What breaks if we remove X?"

The Explanation Ladder

Generate explanations at each level, with each building on the last:

Level 1: ELI5 (1 paragraph)

  • No jargon, no equations
  • Use familiar analogies from everyday life
  • A curious 10-year-old should roughly get it

Level 2: Undergraduate (2-3 paragraphs)

  • Assume calculus, basic linear algebra, intro ML
  • Introduce key terms with definitions
  • Connect to textbook concepts they'd know

Level 3: Graduate (3-4 paragraphs)

  • Assume ML fundamentals, optimization, probability
  • Discuss relationship to prior work
  • Explain why naive approaches don't work
  • Cover the key equations with plain-English annotations

Level 4: Researcher (2-3 paragraphs)

  • Assume field expertise
  • Subtle technical contributions
  • Limitations and open questions
  • How this changes what's possible

Key Equations Breakdown

For each important equation:

[Equation in LaTeX]

In words: [Plain English translation]

Each term:
- [symbol]: [what it represents] [why it's there]

Intuition: [Why this mathematical form? What would change if we used a different form?]

Visual Intuition Artifact

Generate a self-contained HTML file with:

  • Architecture diagram - Boxes and arrows showing information flow
  • Interactive sliders - Manipulate key parameters, see effects
  • Before/after comparisons - What the method improves over baselines
  • Failure case visualization - When and why it breaks down

Use SVG for diagrams, vanilla JavaScript for interactivity. Dark theme, clean typography.

<!DOCTYPE html>
<html>
<head>
  <title>[Paper Name] - Visual Intuition</title>
  <style>
    :root { --bg: #1a1a2e; --text: #eee; --accent: #4f8cff; }
    /* Clean, research-aesthetic styling */
  </style>
</head>
<body>
  <h1>[Paper Title]</h1>
  <p class="tldr">[One-sentence insight]</p>

  <section id="architecture">
    <svg><!-- Information flow diagram --></svg>
  </section>

  <section id="interactive">
    <!-- Parameter sliders with live updates -->
  </section>

  <section id="comparisons">
    <!-- Before/after, ablations -->
  </section>
</body>
</html>

The "What Breaks?" Analysis

For each major component, explain:

  1. What it does - The role this component plays
  2. What breaks without it - Concrete failure mode
  3. Why this solution - Alternatives considered, why this won
  4. The tradeoff - What we pay for this choice (compute, complexity, assumptions)

Output Structure

Deliver as a structured document:

# [Paper Title]

**TL;DR:** [One sentence]

**Why it matters:** [One paragraph on significance]

## The Explanation Ladder

### ELI5
[...]

### Undergraduate Level
[...]

### Graduate Level
[...]

### Researcher Level
[...]

## Key Equations

### Equation 1: [Name]
[Breakdown as specified above]

## What Breaks If We Remove...

### [Component 1]
[Analysis]

### [Component 2]
[Analysis]

## Visual Intuition

[Link to or embed HTML artifact]

## Further Reading

- [Prerequisite paper 1]
- [Follow-up work 1]

Quality Standards

  • Every analogy must be accurate, not just catchy
  • Equations must be explained, not just translated
  • Visuals must reveal structure, not just decorate
  • The researcher-level section should contain insight, not just summary
  • Admit when something is genuinely confusing or poorly explained in the original paper

Research Question Refiner

Transform "I'm interested in X" into "I will investigate whether Y under conditions Z, measuring W."

The Problem

Most research ideas fail not because they're bad, but because they're:

  • Too vague to act on
  • Too ambitious to complete
  • Too incremental to matter
  • Missing a clear success criterion

This skill fixes that.

Process

Stage 1: Excavate the Interest

Start by understanding what's actually pulling at you:

Questions to ask:

  1. What sparked this interest? (Paper, conversation, problem you encountered?)
  2. What's the version that excites you most?
  3. What would be cool if it worked?
  4. Who would care about the answer?

Output: A paragraph capturing the raw interest, unfiltered.

Stage 2: Map the Territory

Before scoping, understand the landscape:

What's Known:

  • What's the current state-of-the-art?
  • What are the established approaches?
  • What have people tried that didn't work?

What's Unknown:

  • What are the acknowledged open problems?
  • What assumptions does current work make?
  • Where do methods fail?

What's Controversial:

  • Where do researchers disagree?
  • What's claimed but not convincingly shown?
  • What's believed but not rigorously tested?

Output: A structured map with citations/references for each area.

Stage 3: Find the Gap

A good research question lives in a gap that is:

PropertyToo LittleJust RightToo Much
NoveltyRedoing existing workNew angle or combinationNo foundation to build on
DifficultyTrivial to answerChallenging but doableRequires breakthroughs
ImpactNo one caresCommunity would update beliefsNobel prize (unrealistic)
ScopeOne experimentThesis chapter / paperMultiple PhDs

Gap-finding questions:

  • What would change if we relaxed assumption X?
  • What if we applied method A to domain B?
  • What's between approach X and approach Y?
  • What fails in setting Z that works elsewhere?

Output: 3-5 candidate gaps, each as one sentence.

Stage 4: Refine to Concrete Question

For each candidate gap, sharpen into a question:

The Formula:

[Action verb] + [specific phenomenon] + [under conditions] + [measurable outcome]

Examples of refinement:

❌ Vague: "How can we make transformers more efficient?" ✅ Concrete: "Does structured sparsity in attention patterns preserve performance on long-context tasks while reducing compute by >50%?"

❌ Vague: "Can robots learn from humans better?" ✅ Concrete: "Does incorporating gaze direction in demonstrations improve sample efficiency for manipulation tasks compared to kinesthetic teaching alone?"

❌ Vague: "What makes language models hallucinate?" ✅ Concrete: "Do retrieval-augmented models hallucinate less on factual questions when retrieval confidence is used to modulate generation temperature?"

Stage 5: Feasibility Check

For each refined question, assess:

Resources Required:

  • Compute: GPU-hours estimate
  • Data: Available or needs collection?
  • Time: Weeks/months realistically
  • Expertise: What skills are needed?

Risk Assessment:

  • What's the probability this works at all?
  • What if the hypothesis is wrong? (Is negative result publishable?)
  • What could go wrong technically?
  • What could invalidate the whole direction?

Dependencies:

  • Does this require other work to finish first?
  • Are there rate-limiting steps?
  • What can be parallelized?

Stage 6: The Litmus Tests

A good research question passes all of these:

The Advisor Test:

"If I pitched this in 2 minutes, would a busy professor say 'yes, go do that' rather than 'hmm, let's talk more'?"

The Paper Test:

"Can I envision the title, abstract, and figure 1 of the resulting paper?"

The Null Result Test:

"If my hypothesis is wrong, would that still be interesting to report?"

The Motivation Test:

"Am I actually excited to work on this for 6+ months?"

The Explanation Test:

"Can I explain why this matters to a smart non-expert in 60 seconds?"

Output Format

Deliver a Research Question Brief:

# Research Question Brief

## The Interest (Raw)
[Original unfiltered interest]

## Territory Map

### What's Known
- [Point 1] ([citation])
- [Point 2] ([citation])

### What's Unknown
- [Open question 1]
- [Open question 2]

### What's Controversial
- [Debate 1]

## Candidate Gaps
1. [Gap 1]
2. [Gap 2]
3. [Gap 3]

## Refined Questions

### Question 1: [Title]
**Statement:** [Precise question]
**Hypothesis:** [What you expect to find]
**Feasibility:** [Brief assessment]
**If it works:** [Impact]
**If it doesn't:** [What we still learn]

### Question 2: [Title]
[Same structure]

## Recommendation
[Which question to pursue and why]

## Immediate Next Steps
1. [Concrete action 1]
2. [Concrete action 2]
3. [Concrete action 3]

Common Failure Modes

The Kitchen Sink: Trying to answer too many questions at once → Fix: Ruthlessly cut until there's ONE core question

The Solution in Search of a Problem: Starting with a method, not a question → Fix: Ask "Who has this problem? Why hasn't it been solved?"

The Incremental Trap: Small delta on existing work → Fix: Ask "Would this change how people think?"

The Impossible Dream: Beautiful question, can't be answered → Fix: Ask "What's the minimal version that's still interesting?"

The Boring Sure Thing: Will definitely work, nobody cares → Fix: Add ambition until there's meaningful risk

Research Taste Developer

Research taste is the ability to distinguish work that matters from work that doesn't - before the community tells you. This skill helps you develop that instinct.

What is Research Taste?

It's the intuition that lets experienced researchers:

  • Pick problems that turn out to be important
  • Know when an idea is "close" vs. "far" from working
  • Recognize a good result even with imperfect execution
  • Predict which papers will be remembered in 5 years

Taste isn't magic - it's pattern recognition from deep exposure. This skill accelerates that exposure.

Process

Phase 1: Analyze the Field

Pick a specific subfield. We'll study what "good" looks like there.

Questions to investigate:

  1. What are the 10 most-cited papers of the last 5 years?
  2. What are the 5 papers experts say "changed how we think"?
  3. What are the best papers from top venues (NeurIPS, ICML, CVPR, etc.)?
  4. What got awards? What got invited talks?

For each landmark paper, analyze:

  • What was the state before this paper?
  • What's the single core insight?
  • What specifically made people cite it?
  • Was it obvious in hindsight?

Phase 2: Pattern Recognition

Look for what the great papers have in common:

The Patterns of Impact:

1. The New Primitive

Papers that introduce a building block others build on.

  • Examples: Attention mechanism, ResNet skip connections, Dropout
  • Pattern: Simple idea, surprisingly general applicability
  • Why it works: Reduces friction for future work
2. The Surprising Connection

Papers that link two previously separate areas.

  • Examples: VAE (variational inference + neural nets), NeRF (neural nets + ray marching)
  • Pattern: "X, but for Y" where the combination is non-obvious
  • Why it works: Cross-pollinates communities
3. The Scaling Insight

Papers showing that scale changes qualitative behavior.

  • Examples: GPT-3, Chinchilla
  • Pattern: What everyone "knew" was wrong at sufficient scale
  • Why it works: Forces field to update beliefs
4. The Rigorous Foundation

Papers that formalize what was previously folklore.

  • Examples: Theoretical convergence proofs, generalization bounds
  • Pattern: Makes hand-wavy intuitions precise
  • Why it works: Enables confident building
5. The Elegant Solution

Papers that solve a problem far more simply than expected.

  • Examples: Simple baseline papers, "X is all you need"
  • Pattern: Previous solutions were overcomplicated
  • Why it works: Shifts field's complexity assumptions

Phase 3: Anti-Patterns

Learn to recognize work that won't age well:

The Incremental Treadmill:

  • Pattern: +0.5% on benchmark with architectural tweak
  • Why it fails: No one remembers or uses it
  • Exception: When it reveals something fundamental

The Method Mashing:

  • Pattern: "We combine A, B, C, and D"
  • Why it fails: No insight about why the combination works
  • Exception: When combination reveals unexpected interaction

The Benchmark Overfitter:

  • Pattern: Method that works only on specific benchmarks
  • Why it fails: Doesn't transfer, forgotten when benchmarks change
  • Exception: When it exposes benchmark weaknesses

The Complexity Monster:

  • Pattern: Works but requires 47 hyperparameters and 3 loss terms
  • Why it fails: No one can reproduce or build on it
  • Exception: Rarely

The Solution Without a Problem:

  • Pattern: Novel method without compelling use case
  • Why it fails: "Interesting but why?"
  • Exception: When use case emerges later (rare)

Phase 4: Develop Your Own Taste

Exercise 1: Prediction Game Before reading a paper, predict based on title/abstract:

  • Will this paper be cited >100 times in 5 years?
  • Write down your prediction and reasoning
  • Track your accuracy over time
  • Analyze where your predictions went wrong

Exercise 2: Explain the Gap For any two papers in citation count:

  • Paper A: 2000 citations
  • Paper B: 50 citations (same venue, same year)
  • What explains the difference?
  • Write a paragraph explanation

Exercise 3: The Time Machine Pick a highly-cited paper. Go back to when it was published:

  • What was the state of the field?
  • Would you have recognized its importance?
  • What signals would you have looked for?

Exercise 4: Design a Hit Given current state of a field:

  • What's the most important open problem?
  • What would a "great paper" on this look like?
  • What would make people cite it?

Phase 5: Meta-Principles

What top researchers seem to do differently:

Problem Selection:

  • Work on problems that are "ready" (pieces exist, no one assembled them)
  • Avoid problems that are stuck for fundamental reasons
  • Pick problems where you have unfair advantages

Execution Taste:

  • Know when to stop polishing (diminishing returns)
  • Know when result is "strong enough" to share
  • Prefer simple-that-works over complex-that-works-slightly-better

Communication Taste:

  • Lead with the insight, not the method
  • Make contribution obvious in first 2 minutes
  • Anticipate and address likely objections

Portfolio Taste:

  • Mix safe and risky projects
  • Build a coherent research identity
  • Create compound interest (each paper enables the next)

Output: Taste Development Report

# Research Taste Analysis: [Field/Subfield]

## Landmark Paper Analysis

### [Paper 1 Title] ([Year])
- **Pre-existing state:** [What was true before]
- **Core insight:** [One sentence]
- **Why it's cited:** [Specific reason]
- **Pattern type:** [New Primitive / Connection / etc.]

### [Paper 2 Title]
[Same structure]

## Pattern Distribution
In this subfield, highly-cited papers tend to be:
- [X]% New Primitives
- [Y]% Surprising Connections
- [Z]% Other

## Anti-Pattern Warnings
The following patterns are common but don't lead to impact:
1. [Anti-pattern common in this field]
2. [Another one]

## Taste Heuristics for [Field]
When evaluating a paper in this field, ask:
1. [Field-specific question that distinguishes good from meh]
2. [Another one]
3. [Another one]

## Current Opportunities
Based on this analysis, promising directions seem to be:
1. [Direction 1]: [Why it's ripe]
2. [Direction 2]: [Why it's ripe]

## Your Taste Development Exercises
1. [Specific exercise for this field]
2. [Another one]

The Ultimate Test

You have good taste when:

  • You're bored by work others find impressive (correctly predicting it won't matter)
  • You're excited by work others overlook (correctly predicting it will matter)
  • Your intuitions about importance are calibrated with reality
  • You can articulate why something is good, not just that it is

This takes years. But deliberate practice - not just reading, but analyzing - accelerates it dramatically.

Reviewer 2 Simulator

Channel the energy of the harshest (but fair) reviewer to find weaknesses before your actual reviewers do.

The Mindset

Reviewer 2 is:

  • Skeptical but not hostile
  • Technically rigorous
  • Short on time (will skim, not read carefully)
  • Looking for reasons to reject (high-volume venues)
  • But wants to champion good work

Reviewer 2 is NOT:

  • Trying to be mean
  • Unfamiliar with the field (usually)
  • Unable to be convinced by good arguments

Process

Phase 1: First Pass (5-minute skim)

Read like a busy reviewer would:

  • Title and abstract
  • Figures and captions
  • Section headers
  • Conclusion

First-pass questions:

  1. Can I understand the contribution from abstract alone?
  2. Do the figures tell the story?
  3. Is this obviously incremental or obviously interesting?
  4. Any immediate red flags?

Phase 2: Deep Read Critique

Go section by section:

Abstract
  • Clear problem statement?
  • Specific contribution (not vague "we propose...")?
  • Key result with number?
  • Any overclaims?

Common issues:

  • "We achieve state-of-the-art" without specifying where/what
  • "Novel" without explaining what's actually new
  • Claims not supported in the paper
Introduction
  • Motivation compelling?
  • Gap in prior work clearly identified?
  • Contribution stated precisely?
  • Paper organization clear?

Common issues:

  • Straw-man characterization of prior work
  • Gap is manufactured, not real
  • Contribution buried in paragraph 4
Related Work
  • Comprehensive coverage?
  • Fair characterization of prior work?
  • Clear differentiation from closest work?
  • Missing obvious citations?

Common issues:

  • Missing direct competitors
  • Misrepresenting prior work to look better
  • No clear statement of difference from closest work
Method
  • Technically sound?
  • Reproducible from description?
  • Assumptions stated explicitly?
  • Notation consistent?

Common issues:

  • Hand-wavy justification
  • Critical details in appendix (or missing entirely)
  • Unstated assumptions
  • Notation changes mid-paper
Experiments
  • Baselines appropriate and strong?
  • Metrics justified?
  • Ablations support claims?
  • Statistical significance addressed?
  • Error bars / variance reported?

Common issues:

  • Weak or outdated baselines
  • Metric chosen to favor method
  • Missing ablations for key components
  • Single seed results
  • Cherry-picked examples
Results/Analysis
  • Claims supported by evidence?
  • Alternative explanations considered?
  • Limitations acknowledged?
  • Failure cases shown?

Common issues:

  • Overclaiming from marginal improvements
  • Ignoring results that don't fit narrative
  • No discussion of when method fails
Conclusion
  • Restates contribution accurately?
  • Future work is genuine (not hand-wavy)?
  • Doesn't introduce new claims?

Phase 3: The Killer Questions

These are the questions that sink papers:

Novelty:

  • "How is this different from [X]?" (where X is obvious prior work)
  • "Why couldn't you just do [simpler thing]?"
  • "What's the actual technical contribution?"

Significance:

  • "Why should anyone care about this?"
  • "What changes if this paper exists vs. doesn't?"
  • "Is this solving a real problem or a made-up one?"

Soundness:

  • "How do you know [claim]?"
  • "What if [assumption] is violated?"
  • "Did you try [obvious baseline]?"

Clarity:

  • "What exactly do you mean by [term]?"
  • "How would someone reproduce this?"
  • "Why is [unexplained design choice] the right choice?"

Phase 4: Scoring

Rate on standard conference criteria:

CriterionScore (1-5)Justification
NoveltyHow new is this?
SignificanceHow much does it matter?
SoundnessIs it technically correct?
ClarityIs it well-written?
ReproducibilityCould I implement this?

Overall Recommendation:

  • Strong Accept: Top 5%, must be in conference
  • Weak Accept: Above threshold, would be OK to accept
  • Borderline: Could go either way
  • Weak Reject: Below threshold, but not fatally flawed
  • Strong Reject: Fundamental issues

Output Format

# Reviewer 2 Report: [Paper Title]

## Summary (2-3 sentences)
[What the paper does and claims]

## Strengths
1. [Strength 1]
2. [Strength 2]
3. [Strength 3]

## Weaknesses

### Major Issues (any one is grounds for rejection)
1. **[Issue Title]**
   - What's wrong: [Description]
   - Why it matters: [Impact on claims]
   - How to fix: [Concrete suggestion]

### Minor Issues (should be fixed but not fatal)
1. **[Issue Title]**
   - [Description and suggestion]

### Nitpicks (take or leave)
- [Small thing 1]
- [Small thing 2]

## Questions for Authors
1. [Question that must be answered]
2. [Question that would strengthen paper]

## Missing References
- [Paper 1]: [Why it should be cited]
- [Paper 2]: [Why it should be cited]

## Scores
| Criterion | Score | Notes |
|-----------|-------|-------|
| Novelty | X/5 | |
| Significance | X/5 | |
| Soundness | X/5 | |
| Clarity | X/5 | |

## Overall Assessment
**Recommendation:** [Accept/Reject with confidence]

**In one sentence:** [The core issue or strength]

## Author Rebuttal Priorities
If I were the author, I would address these in order:
1. [Most important thing to address]
2. [Second most important]
3. [Third]

Calibration Notes

Reviewer 2 is harsh but fair:

  • Points out real issues, not imagined ones
  • Suggests fixes, not just complaints
  • Acknowledges strengths genuinely
  • Would update opinion if given good rebuttal

Reviewer 2 is NOT:

  • Dismissive without reason
  • Demanding impossible experiments
  • Rejecting due to missing tangential work
  • Penalizing for honest limitations

Turn This Feature Into a Blog Post

Generate a Markdown blog post that explains a code implementation in an engaging, educational way.

Process

  1. Analyze the implementation - Read and understand all relevant code files, tracing the feature from entry point to completion
  2. Identify the narrative - Find the core problem being solved and why it matters
  3. Structure the post - Organize as What → Why → How (from first principles)
  4. Write accessibly - Use friendly, conversational language while maintaining technical authority
  5. Output Markdown - Create a complete .md file ready for publishing

Blog Post Structure

Title

  • Clear, specific, and searchable
  • Format: "How We Built [Feature]" or "Building [Feature]: A Deep Dive"

Introduction (2-3 paragraphs)

  • Hook the reader with the problem or outcome
  • Briefly explain what the feature does
  • Preview what readers will learn

The What (1-2 sections)

  • Describe the feature from the user's perspective
  • Include screenshots or diagrams if applicable
  • Keep technical jargon minimal

The Why (1-2 sections)

  • Explain the problem this solves
  • Discuss alternatives considered and why this approach won
  • Connect to broader engineering principles

The How (2-4 sections)

  • Walk through the implementation from first principles
  • Include relevant code snippets with explanations
  • Explain non-obvious decisions
  • Build up complexity gradually

Conclusion

  • Summarize key takeaways
  • Mention potential future improvements
  • Invite engagement (questions, feedback)

Writing Style

  • Friendly but authoritative - Write like a knowledgeable colleague explaining over coffee
  • First-person plural - Use "we" to create shared ownership
  • Active voice - "We built" not "It was built"
  • Show, don't just tell - Use code examples liberally
  • Explain the "why" - Every code block should have context
  • Avoid jargon walls - Define terms on first use

Code Snippets

  • Include only relevant portions, not entire files
  • Add comments for non-obvious lines
  • Use syntax highlighting with language tags
  • Provide context before each snippet

Output

Save the blog post as a Markdown file with:

  • Kebab-case filename matching the title
  • Frontmatter with title, date, author, and tags (if appropriate for the target platform)
  • Properly formatted headers, code blocks, and lists

Sponsors

Details

Marketplace
GhostScientist/skills
Category
Community

More from GhostScientist/skills

All 5