
writing-skills
Skills for technical writing and content creation
- GitHub stars
- 5
Install
/plugin install writing-skills@GhostScientist-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add GhostScientist/skills.
Contents
Discovered from sourceSkills 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
- Project Discovery - Analyze project structure, patterns, architecture
- Feature Mapping - Identify watchOS-suitable features and priorities
- API Compatibility - Search web for current watchOS API availability
- Architecture Planning - Design watchOS-specific architecture
- Plan Generation - Create phased plan with warnings and alternatives
- 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
- Glanceability - Visible within 2 seconds
- Minimal Interaction - 1-3 taps max
- Context Awareness - Time, location, activity
- Battery Conscious - Efficient refresh, TimelineSchedule
- Haptic Feedback - Confirm actions appropriately
SwiftUI Gotchas
- Avoid nested TabViews (memory leaks)
- Use TimelineSchedule for efficient metric updates
- Check
isLuminanceReducedto 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:
- Executive Summary
- ⚠️ API Compatibility Warnings table
- Phased implementation tasks
- 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:
- API Warnings: [N] APIs unavailable—alternatives documented.
- Recommended Features: [list] prioritized for Watch.
- 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:
- What specific claim will this experiment support or refute?
- What would convince a skeptical reviewer?
- 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):
| Variable | Levels | Rationale |
|---|---|---|
| [Var 1] | [Level A, B, C] | [Why these levels] |
Dependent Variables (what you measure):
| Metric | How Measured | Why This Metric |
|---|---|---|
| [Metric 1] | [Procedure] | [Justification] |
Control Variables (what you hold constant):
| Variable | Fixed Value | Why Fixed |
|---|---|---|
| [Var 1] | [Value] | [Prevents confound X] |
Step 3: Choose Baselines
Every experiment needs comparisons. No result is meaningful in isolation.
Baseline Hierarchy:
-
Random/Trivial Baseline
- What does random chance achieve?
- Sanity check that the task isn't trivial
-
Simple Baseline
- Simplest reasonable approach
- Often embarrassingly effective
-
Standard Baseline
- Well-known method from literature
- Apples-to-apples comparison
-
State-of-the-Art Baseline
- Current best published result
- Only if you're claiming SOTA
-
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:
| Variant | What's Removed/Changed | Expected Effect | If No Effect... |
|---|---|---|---|
| Full Model | Nothing | Best performance | - |
| w/o Component A | Remove A | Performance drops X% | A isn't helping |
| w/o Component B | Remove B | Performance drops Y% | B isn't helping |
| Component A only | Only A, no B | Shows 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:
| Confound | How to Check | How to Control |
|---|---|---|
| Hyperparameter tuning advantage | Same tuning budget for all | Report tuning procedure |
| Compute advantage | Matched FLOPs/params | Report compute used |
| Data leakage | Check train/test overlap | Strict separation |
| Random seed luck | Multiple seeds | Report variance |
| Implementation bugs (baseline) | Verify baseline numbers | Use official implementations |
| Cherry-picked examples | Random or systematic selection | Pre-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:
| Comparison | Test | Assumptions |
|---|---|---|
| Two methods, normal data | t-test | Normality, equal variance |
| Two methods, unknown dist | Mann-Whitney U | Ordinal data |
| Multiple methods | ANOVA + post-hoc | Normality |
| Multiple methods, unknown | Kruskal-Wallis | Ordinal data |
| Paired comparisons | Wilcoxon signed-rank | Same test instances |
Avoid:
- p-hacking (running until significant)
- Multiple comparison problems (Bonferroni correct)
- Reporting only favorable metrics
Step 7: Compute Budget
Before running, estimate:
| Component | Estimate | Notes |
|---|---|---|
| Single training run | X GPU-hours | [Details] |
| Hyperparameter search | Y runs × X hours | [Search strategy] |
| Baselines | Z runs × W hours | [Which baselines] |
| Ablations | N variants × X hours | [Which ablations] |
| Seeds | M seeds × above | [How many seeds] |
| Total | T GPU-hours | Buffer: 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
- Analyze the model — full model, LoRA adapter, or Inference API supported.
- Choose a deployment strategy from that analysis.
- Ask the user if the model type or cost preference is unclear.
- Deploy with
scripts/deploy_model.py, or assemble the Space manually. - Set the runtime hardware in Space Settings.
- 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.0andhuggingface_hub>=0.26.0. Do not pin Gradio to an old exact patch version —gradio==4.44.0raisesImportError: cannot import name 'HfFolder'. - Gradio 5.x requires nested lists for examples:
[["ex1"], ["ex2"]], not["ex1", "ex2"]. - LoRA Spaces must include
peftinrequirements.txt. - Keep
sdk_versionin the README frontmatter consistent with thegradioversion inrequirements.txt. - Hardware pricing changes; point users to https://huggingface.co/docs/hub/spaces-gpus rather than quoting rates.
Bundled files
| Path | Contents |
|---|---|
scripts/deploy_model.py | Auto-detecting end-to-end deployment (preferred path) |
scripts/create_space.py | Create a scaffolded, empty Space |
scripts/manage_space.py | Hardware, secrets, pause/restart for existing Spaces |
references/model-analysis.md | Model type detection, Inference API signals, hardware tiers |
references/manual-deployment.md | Hand-assembly walkthrough and template selection |
references/troubleshooting.md | Build 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:
-
Identify the core algorithm - Strip away ablations, extensions, bells and whistles. What's the minimal version?
-
List the components - Break into modules:
- Data pipeline
- Model architecture
- Loss function(s)
- Training loop
- Evaluation metrics
-
Find the tricky parts - What's non-obvious?
- Custom layers or operations
- Numerical stability concerns
- Hyperparameter sensitivity
- Implementation details buried in appendices
-
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):
-
The Overfit Test
- Can you memorize 1 example? 10? 100?
- If not, architecture or gradient bug
-
The Gradient Check
- Are gradients flowing to all parameters?
- Any NaN or exploding gradients?
-
The Initialization Check
- Match paper's initialization exactly
- This matters more than people think
-
The Learning Rate Sweep
- Log scale: 1e-5 to 1e-1
- Loss should decrease for some range
-
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:
- Numbers match - Within reasonable variance of paper's results
- Understanding is deep - You can explain every line of code
- You found the gotchas - You know what breaks and why
- 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:
- Renders the icon design at 1024x1024 (the master size)
- Includes iOS-style rounded corners (superellipse, not CSS border-radius)
- Shows a preview grid of all sizes to verify readability
- Provides a download mechanism for each size
Required Sizes
Generate all iOS app icon sizes:
| Size | Purpose |
|---|---|
| 1024x1024 | App Store |
| 180x180 | iPhone (@3x) |
| 167x167 | iPad Pro (@2x) |
| 152x152 | iPad (@2x) |
| 120x120 | iPhone (@2x) |
| 87x87 | Spotlight (@3x) |
| 80x80 | Spotlight (@2x) |
| 76x76 | iPad (@1x) |
| 60x60 | iPhone (@1x) |
| 58x58 | Settings (@2x) |
| 40x40 | Spotlight (@1x) |
| 29x29 | Settings (@1x) |
| 20x20 | Notification (@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
- Ask about the app's purpose, name, and any existing brand colors
- Write the Icon Philosophy
- Describe 2-3 concept directions with rationale
- Get user approval on a direction
- Generate the HTML artifact with full icon set
- 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
- Get the paper - Ask for the arXiv link, PDF, or paper title
- Extract the core - Identify the single key insight (one sentence)
- Build the ladder - Create explanations at 4 levels
- Visualize intuition - Generate interactive diagrams
- 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:
- What it does - The role this component plays
- What breaks without it - Concrete failure mode
- Why this solution - Alternatives considered, why this won
- 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:
- What sparked this interest? (Paper, conversation, problem you encountered?)
- What's the version that excites you most?
- What would be cool if it worked?
- 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:
| Property | Too Little | Just Right | Too Much |
|---|---|---|---|
| Novelty | Redoing existing work | New angle or combination | No foundation to build on |
| Difficulty | Trivial to answer | Challenging but doable | Requires breakthroughs |
| Impact | No one cares | Community would update beliefs | Nobel prize (unrealistic) |
| Scope | One experiment | Thesis chapter / paper | Multiple 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:
- What are the 10 most-cited papers of the last 5 years?
- What are the 5 papers experts say "changed how we think"?
- What are the best papers from top venues (NeurIPS, ICML, CVPR, etc.)?
- 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:
- Can I understand the contribution from abstract alone?
- Do the figures tell the story?
- Is this obviously incremental or obviously interesting?
- 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:
| Criterion | Score (1-5) | Justification |
|---|---|---|
| Novelty | How new is this? | |
| Significance | How much does it matter? | |
| Soundness | Is it technically correct? | |
| Clarity | Is it well-written? | |
| Reproducibility | Could 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
- Analyze the implementation - Read and understand all relevant code files, tracing the feature from entry point to completion
- Identify the narrative - Find the core problem being solved and why it matters
- Structure the post - Organize as What → Why → How (from first principles)
- Write accessibly - Use friendly, conversational language while maintaining technical authority
- Output Markdown - Create a complete
.mdfile 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