CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

A Claude Code skill (invoked via /paper-writing) that encodes the writing methodology of the Systems and Networking Lab (SNL) at UC Santa Barbara. Part of a three-skill family (literature-survey, data-visualization, paper-writing) that compresses the operational middle of the research pipeline. It is not a traditional codebase — there is no build system, no tests, and no application code. The repo contains markdown files that Claude reads at runtime to enforce editorial rules, rhetorical move sequences, and a structured writing pipeline.

Installation

./setup

This copies skill files into ~/.claude/skills/paper-writing/. Always edit files in this repo, then re-run ./setup to propagate changes.

Architecture

SKILL.md is the main entry point Claude reads when /paper-writing is invoked. It defines:

• The three-layer model: fixed pipeline → customizable voice/editorial rules → per-paper project context
• The five-stage writing pipeline: Brainstorming → Architecture → Section Drafts → Integration → Compression
• The mandatory style audit gate (runs on every tex edit)
• Section checklist and rhetorical move dispatch tables

author_profile/ contains the editorial rules (source of truth for all style enforcement). The style layer is organized into three files by mechanism — one mechanical gate, one semantic gate, one positive craft reference:

• editorial_principles.md — 14 cross-paper principles with evidence from forensic revision analysis
• craft_reference.md — how to write (the positive layer): sentence-level style (~21-word mean, claim-first, active voice, named-over-vague) and three registers (base/terse, conceptual/position, warm/narrative)
• gate_mechanical.md — the single greppable style gate (M1–M18): em-dashes, antithesis, intensifiers, banned/pompous/fancy words, passive voice, wordiness, term-drift — one grep script
• gate_semantic.md — the single reader-judgment gate (S1–S31): define-before-use, followability, coherence/consistency, rigor/grounding, honest positioning, figures, closure gate
• compression_patterns.md — 7 compression operations with before/after examples
• rhetorical_moves.md — cross-section move sequences
• intervention_types.md — 7 advisor intervention types for draft review

writing_checklists/ contains post-draft structural checklists (intro, evaluation, design, related work). These run automatically after every section draft.

section_rhetorical_moves/ contains detailed per-section move sequences with concrete examples from accepted/rejected papers.

brainstorming_guide.md defines the 34-question, 6-phase brainstorming workflow that produces a project_context.md.

story_mode.md defines the ten-step workflow (with a short path) that turns an existing record (notes, drafts, code, related work) into a paper story, an outline and a calibration spec.

USAGE.md is the student-facing guide: first session, which mode for which situation, outputs, iteration, other skills, customizing, privacy.

This repository is public. Every example must be synthetic. A group's real cases, project records and internal notes belong in a private overlay skill (an installed skill whose name ends in paper-writing-lab), never here.

figure_synthesis_guide.md defines the 3-mode workflow (spec → generate → critique) for non-data figures — architecture diagrams, pipeline illustrations, concept diagrams, comparison schematics. Uses a hybrid approach: AI image generation prompts (Gemini/DALL-E) for visually rich figures, TikZ for precise structural figures.

figure_templates/ contains supporting files for figure synthesis:

• venue_styles.md — column widths, fonts, color palette, and styling blocks for NSDI/SIGCOMM/IMC
• prompt_templates.md — AI image generation prompt skeletons per archetype (architecture overview, concept illustration, comparison schematic, deployment diagram)
• tikz_skeletons.md — TikZ starter templates per archetype (pipeline flow, component detail, taxonomy)
• figure_spec_template.md — per-figure spec template (filled during spec mode, consumed during generate mode)

examples/ contains the project_context.md template and a fully synthetic completed example (example_project_context.md).

Key Design Decisions

• Introduction-twice is the most impactful principle. The introduction is written twice: Draft 0 (framing scaffold) before the evaluation, then the final introduction rewritten from scratch after the evaluation. Section drafts follow: Draft 0 Introduction → Evaluation → Design → Background → Related Work → Final Introduction → Abstract.
• project_context.md is generated per-paper in the user's working directory (not in this repo). It should be gitignored.
• The setup script copies a specific subset of files (SKILL.md, brainstorming_guide.md, story_mode.md, figure_synthesis_guide.md, red_team_protocol.md, loop_mode.md, author_profile/, writing_checklists/, section_rhetorical_moves/, figure_templates/, examples/) — it intentionally excludes README.md and setup itself.
• Voice rules ship as defaults from the SNL lab. Students customize by editing author_profile/ files after installation.
• Signposting through claims: section preambles are encouraged when they state the section's conclusion, but banned when content-free ("In this section, we describe...").
• Topic-sentence-first drafting: before writing full prose for any section, write all topic sentences and verify they form a coherent argument. This intermediate scaffolding step sits between Architecture (section outline) and full drafting.