academic-writing-cs

What this skill does

# Academic Writing for Computer Science

## Overview

This skill provides end-to-end support for writing high-quality computer science research papers. It focuses on constructing clear, compelling technical narratives while adhering to field-specific conventions.

**Core Philosophy:**
- Academic papers are **narrative arcs** (Problem → Solution → Evidence → Implications), not template fill-ins
- Clarity comes from structure: place familiar information first, new information last
- Every design choice must be justified; every claim must be supported

**Scope:**
- Conference papers (6-12 pages, competitive venues)
- Journal articles (15-30 pages, comprehensive)
- Thesis chapters (flexible length, deep coverage)
- All CS subfields: AI/ML, Systems, Theory, HCI, Security, etc.

---

## When to Use This Skill

Invoke this skill when:
- Planning paper structure and narrative flow
- Drafting any section (Abstract, Introduction, Methods, Results, Discussion, Conclusion)
- Revising for clarity, coherence, or compliance with venue requirements
- Reviewing sentence-level writing for clarity issues
- Seeking CS-specific conventions (notation, figures, citations)
- Checking completeness with section-by-section quality checklists
- Responding to reviewer comments

---

## Workflow Decision Tree

### Stage 1: Planning and Structure

**When starting a new paper or major revision:**

1. **Define the Narrative Arc**
   - What problem does this solve, and why does it matter? (1-2 sentences)
   - What is the single main contribution? (1 sentence)
   - What are the 3 key results that support the contribution?
   - What are the main limitations?

   **Reference:** `references/narrative_framework.md` — Read the "Core Principle" and "Section-Level Narrative Structure" sections to understand how to structure the paper's story.

2. **Identify Target Venue and Constraints**
   - Conference or journal?
   - Page limits, formatting requirements, anonymization rules?
   - Subfield conventions (ML vs. Systems vs. Theory)?

   **Reference:** `references/cs_conventions.md` (Section 8: Venue-Specific Guidelines, Section 5: Subfield-Specific Conventions)

3. **Outline Section-by-Section**
   - For each major section, define:
     - What is the purpose of this section?
     - What are the 2-3 key points to convey?
     - What figures/tables will support this?

   **Tool:** Use `assets/section_checklists.md` (Quick Pre-Draft Planning Checklist) to ensure all key questions are answered before writing begins.

---

### Stage 2: Drafting

**For each section, follow this process:**

#### Abstract
1. Use the **4-sentence structure**: Context → Gap → Contribution → Impact
2. Check against `assets/section_checklists.md` (Abstract Checklist)
3. Ensure it's self-contained and within word limit (150-250 words)

**Common mistakes:**
- Vague contribution: "We improve X" → Be specific: "We achieve 15% higher accuracy"
- No concrete results: Always include numbers/metrics

---

#### Introduction
1. Follow the **funnel structure**: Broad → Narrow → Specific
   - Para 1: Problem domain and importance
   - Para 2-3: Specific problem, motivation, why existing work falls short
   - Para 4: Gap statement ("However, existing approaches lack...")
   - Para 5: Contribution overview (what this paper provides)
   - Para 6: Results summary (2-3 concrete findings)
   - Para 7: Paper organization (optional)

2. **Key requirement:** By the end of paragraph 4-5, the reader must clearly understand the contribution.

3. Include at least one figure (architecture or key result) for ML/systems papers.

4. Check against `assets/section_checklists.md` (Introduction Checklist)

**Reference:** `references/narrative_framework.md` (Introduction section) for detailed guidance and examples.

---

#### Related Work
1. **Organize thematically** (not chronologically): Group into 3-5 categories
2. For each category:
   - Describe the general approach
   - Cite 3-5 representative works with 1-sentence descriptions
   - Point out limitations relevant to your contribution

3. **End with positioning paragraph**: "In contrast to [X], our approach..."
   - Clearly articulate differences and advantages

4. Check against `assets/section_checklists.md` (Related Work Checklist)

**Common mistakes:**
- Laundry list of citations without synthesis
- Failing to position your work relative to prior work
- Being dismissive (respect prior work while differentiating)

---

#### Methodology
1. **Dual objectives:**
   - Reproducibility: Enough detail for reimplementation
   - Intuition: Explain why the approach works

2. **Structure varies by paper type:**
   - **ML/AI papers**: Problem Formulation → Overview + Figure → Detailed Design → Implementation → Complexity
   - **Systems papers**: Architecture Overview → Component Design → Key Mechanisms → Implementation
   - **Theory papers**: Formal Definitions → Main Results (theorems) → Proof Sketch

3. **Always include:**
   - Clear notation (define all symbols on first use)
   - High-level overview before diving into details
   - Justification for design choices (or defer to Ablations)

4. Check against `assets/section_checklists.md` (Methodology Checklist)

**Reference:** `references/narrative_framework.md` (Methodology section) and `references/cs_conventions.md` (Section 1: Notation and Mathematical Writing)

---

#### Experiments/Results
1. **Experimental Setup** (subsection):
   - Datasets: Size, splits, preprocessing
   - Baselines: What you compare against (with citations)
   - Metrics: What you measure and why
   - Hardware/Software: Infrastructure and versions
   - Hyperparameters: How selected

2. **Main Results** (subsection):
   - Table/figure showing primary comparison
   - Text: "Table 1 shows that our method outperforms..."
   - Highlight key findings with concrete numbers
   - Report statistical significance (confidence intervals, p-values, or std dev)

3. **Ablation Studies** (subsection, critical):
   - Demonstrate necessity of each component
   - Table: effect of removing/modifying components

4. **Analysis** (subsection):
   - Where does the method excel? Where does it fail?
   - Qualitative analysis, error analysis, failure cases

5. **Computational Cost** (if relevant):
   - Training time, inference time, memory usage
   - Comparison with baselines

6. Check against `assets/section_checklists.md` (Experiments/Results Checklist)

**Reference:** `references/narrative_framework.md` (Experiments/Results section)

---

#### Discussion
1. **Summarize findings** (1 para): Restate key results
2. **Interpret results** (1-2 paras): Why does the method work? What insights?
3. **Acknowledge limitations** (0.5-1 para): Be honest about scope and failure cases
4. **Broader implications** (0.5-1 para): Impact on the field, applications, future directions

5. Check against `assets/section_checklists.md` (Discussion Checklist)

**Tone:** Balanced—confident but not overselling. Limitations increase credibility.

---

#### Conclusion
1. **Restate contribution** (1 para): Recap problem, solution, key findings
2. **Broader impact** (0.5 para): Significance and applications
3. **Future work** (0.5 para): Open questions and extensions
   - Phrase as opportunities: "An interesting direction is..." (not "In future work, we will...")

4. Check against `assets/section_checklists.md` (Conclusion Checklist)

**Do NOT:** Introduce new ideas, copy-paste Abstract, or be vague.

---

### Stage 3: Revision for Clarity

**After drafting, apply sentence-level clarity principles:**

#### The Three Golden Rules (Gopen & Swan)

1. **Old Before New**: Start sentences with familiar information; end with new information
   - This creates coherent flow where each sentence builds on what came before

2. **Subject-Verb Proximity**: Keep the verb close to the subject
   - Long gaps between subject and verb strain comprehension

3. **Stress Position Power**: Place the most important information at sentence end
   - Readers remem