# 📋 Common Workflows

> **Step-by-step recipes** for common tasks

**New to the template?** Start with **[Quick Start Cheatsheet](../reference/quick-start-cheatsheet.md)** | **[Getting Started](../guides/getting-started.md)**

## 🎯 "I Want To..." Quick Index

- [Write my first document](#write-my-first-document)
- [Add a new section to manuscript](#add-a-new-section-to-manuscript)
- [Create a figure with data](#create-a-figure-with-data)
- [Add mathematical equations](#add-mathematical-equations)
- [Cross-reference sections and figures](#cross-reference-sections-and-figures)
- [Add a new Python module](#add-a-new-python-module)
- [Write tests for my code](#write-tests-for-my-code)
- [Debug test failures](#debug-test-failures)
- [Fix coverage below requirements](#fix-coverage-below-requirements)
- [Generate PDF of manuscript](#generate-pdf-of-manuscript)
- [Customize project metadata](#customize-project-metadata)
- [Add supplemental materials](#add-supplemental-materials)
- [Contribute to the template](#contribute-to-the-template)

---

## Write My First Document

**Goal**: Create your first professional document from scratch

**Prerequisites**: Template cloned and dependencies installed

**Steps**:

1. **Edit the abstract**

   ```bash
   vim projects/templates/template_code_project/manuscript/01_abstract.md
   ```

2. **Add your content**

   ```markdown
   # Abstract {#sec:abstract}

   Your research summary goes here. Keep it concise (150-250 words).
   ```

3. **Generate the PDF**

   ```bash
   # Run core pipeline (eight stages with --core-only; see RUN_GUIDE.md)
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

4. **View the result**

   ```bash
   open output/templates/template_code_project/pdf/01_abstract.pdf  # Individual section PDFs
   ```

**Expected Result**: Professional PDF with your content formatted

**Next Steps**: Read [Getting Started Guide](../guides/getting-started.md) for more details

---

## Add a New Section to Manuscript

**Goal**: Add a new numbered section to your manuscript

**Prerequisites**: Basic understanding of markdown

**Steps**:

1. **Determine section number**
   - Main sections: 01-09 (e.g., `07_limitations.md`)
   - Supplemental: S01-S99 (e.g., `S03_additional_data.md`)
   - See [Manuscript Numbering](../usage/manuscript-numbering-system.md)

2. **Create the file**

   ```bash
   vim projects/templates/template_code_project/manuscript/07_limitations.md
   ```

3. **Add section header with label**

   ```markdown
   # Limitations {#sec:limitations}

   ## Study Limitations

   This research has several limitations...
   ```

4. **Rebuild manuscript**

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

5. **Reference from other sections**

   ```markdown
   See Section \ref{sec:limitations} for discussion of constraints.
   ```

**Expected Result**: New section appears in correct order in combined PDF

**Troubleshooting**:

- Section not appearing? Check filename starts with number/S-number
- Wrong order? See [Manuscript Numbering](../usage/manuscript-numbering-system.md)

---

## Create a Figure with Data

**Goal**: Generate a figure from data using the thin orchestrator pattern

**Prerequisites**: Understanding of Python and matplotlib

**Steps**:

1. **Create business logic in `projects/{name}/src/`**

   ```bash
   vim projects/templates/template_code_project/src/data_analysis.py
   ```

   ```python
   def analyze_data(values):
       """Analyze data and return statistics."""
       return {
           'mean': sum(values) / len(values),
           'max': max(values),
           'min': min(values)
       }
   ```

2. **Create tests (90% minimum coverage required)**

   ```bash
   vim projects/templates/template_code_project/tests/test_data_analysis.py
   ```

   ```python
   from projects.template_code_project.src.data_analysis import analyze_data

   def test_analyze_data():
       result = analyze_data([1, 2, 3, 4, 5])
       assert result['mean'] == 3.0
       assert result['max'] == 5
       assert result['min'] == 1
   ```

3. **Run tests**

   ```bash
   uv run pytest projects/templates/template_code_project/tests/test_data_analysis.py --cov=projects/templates/template_code_project/src/data_analysis
   ```

4. **Create thin orchestrator script**

   ```bash
   vim projects/templates/template_code_project/scripts/my_analysis_figure.py
   ```

   ```python
   #!/usr/bin/env python3
   import os
   import matplotlib.pyplot as plt
   from projects.template_code_project.src.data_analysis import analyze_data  # Import from project src/

   # Use src/ method for computation
   data = [1, 2, 3, 4, 5]
   stats = analyze_data(data)

   # Script handles visualization only
   fig, ax = plt.subplots()
   ax.bar(['Mean', 'Max', 'Min'],
          [stats['mean'], stats['max'], stats['min']])
   ax.set_title('Data Analysis')

   # Save to output
   output_path = 'projects/{name}/output/figures/my_analysis.png'
   os.makedirs(os.path.dirname(output_path), exist_ok=True)
   fig.savefig(output_path)
   print(output_path)  # Print for manifest
   ```

5. **Run script**

   ```bash
   uv run python projects/templates/template_code_project/scripts/my_analysis_figure.py
   ```

6. **Add to manuscript**

   ```markdown
   \begin{figure}[h]
   \centering
   \includegraphics[width=0.8\textwidth]{../output/figures/my_analysis.png}
   \caption{Statistical analysis of dataset}
   \label{fig:my_analysis}
   \end{figure}
   ```

**Expected Result**: Figure appears in manuscript with professional formatting

**Key Principle**: Business logic in `projects/{name}/src/`, visualization in `projects/{name}/scripts/`

**See Also**: [Thin Orchestrator Pattern](../architecture/thin-orchestrator-summary.md)

---

## Add Mathematical Equations

**Goal**: Add numbered equations with cross-references

**Prerequisites**: Basic LaTeX knowledge

**Steps**:

1. **Write equation with label**

   ```markdown
   \begin{equation}\label{eq:quadratic}
   f(x) = ax^2 + bx + c
   \end{equation}
   ```

2. **Reference equation in text**

   ```markdown
   The quadratic function \eqref{eq:quadratic} has two solutions.
   ```

3. **For multiple equations**

   ```markdown
   \begin{align}
   f(x) &= x^2 + 2x + 1 \label{eq:first} \\
   g(x) &= x^3 - x \label{eq:second}
   \end{align}

   Equations \eqref{eq:first} and \eqref{eq:second} are related.
   ```

4. **Rebuild**

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

**Expected Result**: Numbered equations with clickable references

**Troubleshooting**:

- Equation shows (??) → Check label spelling
- Numbering wrong → Ensure unique labels
- Not rendering → Check LaTeX syntax

**See Also**: [Markdown Template Guide](../usage/markdown-template-guide.md)

---

## Cross-Reference Sections and Figures

**Goal**: Create internal links between document parts

**Prerequisites**: Basic markdown understanding

**Types of References**:

### Section References

```markdown
# Methodology {#sec:methodology}

As described in Section \ref{sec:methodology}...
```

### Equation References

```markdown
\begin{equation}\label{eq:important}
E = mc^2
\end{equation}

From Equation \eqref{eq:important}, we see...
```

### Figure References

```markdown
\begin{figure}[h]
\centering
\includegraphics{../output/figures/plot.png}
\caption{Results}
\label{fig:results}
\end{figure}

Figure \ref{fig:results} shows...
```

### Table References

```markdown
\begin{table}[h]
\caption{Performance metrics}
\label{tab:performance}
...
\end{table}

Table \ref{tab:performance} summarizes...
```

**Validation**:

```bash
uv run python -m infrastructure.validation.cli markdown projects/templates/template_code_project/manuscript/
```

**See Also**: [Markdown Template Guide](../usage/markdown-template-guide.md)

---

## Add a New Python Module

**Goal**: Add new functionality following the thin orchestrator pattern

**Prerequisites**: Python programming knowledge

**Steps**:

1. **Create module in `projects/{name}/src/`**

   ```bash
   vim projects/templates/template_code_project/src/statistics.py
   ```

   ```python
   """Statistical analysis functions."""

   def calculate_variance(values):
       """Calculate sample variance."""
       mean = sum(values) / len(values)
       return sum((x - mean) ** 2 for x in values) / (len(values) - 1)

   def calculate_std_dev(values):
       """Calculate standard deviation."""
       return calculate_variance(values) ** 0.5
   ```

2. **Create tests**

   ```bash
   vim projects/templates/template_code_project/tests/test_statistics.py
   ```

   ```python
   from projects.template_code_project.src.statistics import calculate_variance, calculate_std_dev

   def test_calculate_variance():
       values = [1, 2, 3, 4, 5]
       var = calculate_variance(values)
       assert abs(var - 2.5) < 1e-10

   def test_calculate_std_dev():
       values = [1, 2, 3, 4, 5]
       std = calculate_std_dev(values)
       assert abs(std - 1.5811388) < 1e-6
   ```

3. **Ensure coverage**

   ```bash
   uv run pytest projects/templates/template_code_project/tests/test_statistics.py --cov=projects/templates/template_code_project/src/statistics --cov-report=term-missing
   ```

4. **Use in scripts (thin orchestrator)**

   ```python
   from projects.template_code_project.src.statistics import calculate_std_dev

   data = [1, 2, 3, 4, 5]
   std = calculate_std_dev(data)  # Use src/ method
   # Script handles visualization...
   ```

**Expected Result**: tested module ready for use

**Key Rules**:

- ALL business logic in `projects/{name}/src/`
- test coverage required (90% project, 60% infra)
- Scripts only orchestrate, never implement algorithms

**See Also**: [Thin Orchestrator Pattern](../architecture/thin-orchestrator-summary.md)

---

## Write Tests for My Code

**Goal**: Achieve test coverage for src/ modules

**Prerequisites**: Understanding of pytest

**Steps**:

1. **Create test file**

   ```bash
   vim projects/templates/template_code_project/tests/test_my_module.py
   ```

2. **Import module to test**

   ```python
   from my_module import my_function
   ```

3. **Write test cases**

   ```python
   def test_my_function_basic():
       """Test basic functionality."""
       result = my_function([1, 2, 3])
       assert result == expected_value

   def test_my_function_edge_cases():
       """Test edge cases."""
       assert my_function([]) == default_value
       assert my_function([1]) == single_value

   def test_my_function_errors():
       """Test error handling."""
       with pytest.raises(ValueError):
           my_function(invalid_input)
   ```

4. **Run tests with coverage**

   ```bash
   uv run pytest projects/templates/template_code_project/tests/test_my_module.py --cov=projects/templates/template_code_project/src/my_module --cov-report=term-missing
   ```

5. **Check for missing lines**
   - Lines marked with `>>>>>` are not covered
   - Add tests to cover all branches

6. **Repeat until ≥90%** (project `src/` gate; see [`COUNTS.md`](../_generated/COUNTS.md))

**Expected Result**: All critical code paths tested, coverage requirements met

**Requirements**:

- Statement coverage: **≥90%** on project `src/` (60% infrastructure)
- Branch coverage: tracked when `--cov-branch` enabled
- No mocks: Use data

**See Also**: [Configuration](../../AGENTS.md#configuration-system) | [Testing Guide](../../tests/AGENTS.md) | [Workflow](../core/workflow.md)

---

## Debug Test Failures

**Goal**: Identify and fix failing tests

**Steps**:

1. **Run tests verbosely**

   ```bash
   uv run pytest tests/ -v
   ```

2. **Run specific test**

   ```bash
   uv run pytest projects/templates/template_code_project/tests/test_my_module.py::test_specific_function -v
   ```

3. **Use debugger**

   ```bash
   uv run pytest projects/templates/template_code_project/tests/test_my_module.py --pdb
   ```

4. **Check detailed output**

   ```bash
   uv run pytest tests/ -vv --tb=long
   ```

5. **Common issues**:
   - Import errors → Check `PYTHONPATH`
   - Assertion failures → Check expected vs actual values
   - Coverage failures → Add tests for missing lines

**Troubleshooting Commands**:

```bash
# Show test discovery
uv run pytest --collect-only

# Run with maximum verbosity
uv run pytest -vvv

# Show local variables on failure
uv run pytest -l

# Stop at first failure
uv run pytest -x
```

**See Also**: [FAQ](faq.md#q-how-do-i-debug-test-failures)

---

## Fix Coverage Below Requirements

**Goal**: Achieve required test coverage (90% project, 60% infra)

**Steps**:

1. **Generate coverage report**

   ```bash
   uv run pytest tests/ --cov=src --cov-report=term-missing
   ```

2. **Identify missing lines**
   - Look for lines marked `>>>>>`
   - Note which functions/branches aren't covered

3. **Analyze uncovered code**

   ```bash
   uv run pytest tests/ --cov=src --cov-report=html
   open htmlcov/index.html
   ```

4. **Add tests for uncovered paths**
   - Test all conditional branches (if/else)
   - Test exception handling
   - Test edge cases

5. **Verify improvement**

   ```bash
   uv run pytest tests/ --cov=src --cov-report=term-missing
   ```

**Example - Covering Conditional**:

```python
# Code with uncovered branch
def process(value):
    if value > 0:  # Covered
        return value * 2
    else:  # Not covered - need test
        return 0

# Add test for uncovered branch
def test_process_negative():
    assert process(-5) == 0
```

**Expected Result**: Coverage requirements achieved (90% project, 60% infra)

---

## Generate PDF of Manuscript

**Goal**: Build professional PDF from markdown sources

**Steps**:

1. **Run pipeline (recommended)**

   ```bash
   # Standard core build (eight executor stages by default; no LLM)
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only

   # Or use unified interactive menu
   ./run.sh

   # Run individual stage scripts (each requires --project {name})
   uv run python scripts/pipeline/stage_00_setup.py --project {name}
   uv run python scripts/pipeline/stage_01_test.py --project {name}
   uv run python scripts/pipeline/stage_02_analysis.py --project {name}
   uv run python scripts/pipeline/stage_03_render.py --project {name}
   uv run python scripts/pipeline/stage_04_validate.py --project {name}
   uv run python scripts/pipeline/stage_05_copy.py --project {name}
   # Optional: LLM (06), executive report (07) — see RUN_GUIDE.md
   ```

2. **Check for errors**
   - Tests must pass (project and infrastructure thresholds in `pyproject.toml` / CI)
   - Scripts must succeed
   - Markdown validation must pass
   - PDF compilation must succeed

3. **View output**

   ```bash
   # Combined PDF after copy outputs
   open output/{name}/pdf/{name}_combined.pdf

   # Or working copy under the project tree
   open projects/{name}/output/pdf/{name}_combined.pdf
   ```

**Core pipeline** (`--core-only`, default flags): eight executor stages — clean outputs, environment setup, infrastructure tests, project tests, analysis, PDF rendering, output validation, copy outputs. **Not** part of core: LLM stages (`scripts/pipeline/stage_06_llm_review.py`) and cross-project executive reporting (`scripts/pipeline/stage_07_executive_report.py`).

**Total Time**: Varies by project and machine; the sequence above is ordered as in `PipelineExecutor`.

**Troubleshooting**:

- Tests fail → Fix coverage issues
- Scripts fail → Check imports from src/
- PDF fails → Check pandoc/xelatex installation
- References show ?? → Check label spelling

**See Also**: [Pipeline Orchestration](../RUN_GUIDE.md) | [PDF Validation](../modules/pdf-validation.md)

---

## Customize Project Metadata

**Goal**: Personalize project with your information

**Steps**:

1. **Set environment variables**

   ```bash
   export AUTHOR_NAME="Dr. Jane Smith"
   export AUTHOR_EMAIL="jane.smith@university.edu"
   export AUTHOR_ORCID="0000-0001-2345-6789"
   export PROJECT_TITLE="My Research Project"
   export DOI="10.5281/zenodo.12345678"  # Optional
   ```

2. **Or create `.env` file**

   ```bash
   cp infrastructure/config/.env.template .env
   vim .env
   ```

   Add:

   ```bash
   AUTHOR_NAME="Dr. Jane Smith"
   AUTHOR_EMAIL="jane.smith@university.edu"
   AUTHOR_ORCID="0000-0001-2345-6789"
   PROJECT_TITLE="My Research Project"
   DOI="10.5281/zenodo.12345678"
   ```

3. **Source environment**

   ```bash
   source .env
   ```

4. **Generate with custom metadata**

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

**Applied To**:

- PDF metadata (title, author, date)
- LaTeX document properties
- Generated file headers
- Cross-reference systems

**See Also**: [AGENTS.md Configuration](../../AGENTS.md#configuration-system)

---

## Add Supplemental Materials

**Goal**: Add supplemental sections to manuscript

**Steps**:

1. **Create supplemental file**

   ```bash
   vim manuscript/S03_supplemental_figures.md
   ```

2. **Add content**

   ```markdown
   # Supplemental Figures {#sec:supplemental_figures}

   ## Additional Visualizations

   This section contains extended visualizations...
   ```

3. **Reference from main text**

   ```markdown
   See Section \ref{sec:supplemental_figures} for additional figures.
   ```

4. **Rebuild**

   ```bash
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only
   ```

**Naming Convention**:

- Main sections: `01-09`
- Supplemental sections: `S01-S99`
- Glossary: `98`
- References: `99`

**Order in PDF**:

1. Main sections (01-09)
2. Supplemental sections (S01-S99)
3. Glossary (98)
4. References (99)

**See Also**: [Manuscript Numbering](../usage/manuscript-numbering-system.md)

---

## Contribute to the Template

**Goal**: Improve the template for everyone

**Steps**:

1. **Fork the repository**

   ```bash
   # On GitHub, click "Fork"
   git clone https://github.com/YOUR_USERNAME/template.git
   ```

2. **Create feature branch**

   ```bash
   git checkout -b feature/my-improvement
   ```

3. **Make changes**
   - Follow thin orchestrator pattern
   - Maintain required test coverage
   - Update documentation

4. **Run tests**

   ```bash
   uv run pytest tests/ --cov=src --cov-report=term-missing
   ```

5. **Run build**

   ```bash
   # Core pipeline (eight stages with --core-only)
   uv run python scripts/runner/execute_pipeline.py --project {name} --core-only

   # Or use unified interactive menu
   ./run.sh
   ```

6. **Commit changes**

   ```bash
   git add .
   git commit -m "feat: add feature"
   ```

7. **Push and create PR**

   ```bash
   git push origin feature/my-improvement
   # On GitHub, create Pull Request
   ```

**Contribution Checklist**:

- [ ] Tests pass (infra + project suites for your branch)
- [ ] Coverage maintained/improved
- [ ] Documentation updated
- [ ] Thin orchestrator pattern followed
- [ ] Commit messages clear
- [ ] PR description

**See Also**: [Contributing Guide](../development/contributing.md) | [Code of Conduct](../development/code-of-conduct.md)

---

## 🔗 Related Documentation

- **[Quick Start Cheatsheet](../reference/quick-start-cheatsheet.md)** - One-page reference
- **[Getting Started](../guides/getting-started.md)** - beginner guide
- **[FAQ](../reference/faq.md)** - Common questions
- **[Glossary](../reference/glossary.md)** - Terms and definitions
- **[Guide](../core/how-to-use.md)** - All 12 skill levels

---

**Need more help?** Check the **[FAQ](../reference/faq.md)** or **[Documentation Index](../documentation-index.md)**