gh-k-dense-ai-claude-scientific-writer-claude-scientific-writer/skills/hypothesis-generation/assets/FORMATTING_GUIDE.md

Hypothesis Generation Report - Formatting Quick Reference

Overview

This guide provides quick reference for using the hypothesis generation LaTeX template and style package. For complete documentation, see SKILL.md.

Quick Start

% !TEX program = xelatex
\documentclass[11pt,letterpaper]{article}
\usepackage{hypothesis_generation}
\usepackage{natbib}

\title{Your Phenomenon Name}
\begin{document}
\maketitle
% Your content
\end{document}

Compilation: Use XeLaTeX or LuaLaTeX for best results

xelatex your_document.tex
bibtex your_document
xelatex your_document.tex
xelatex your_document.tex

Color Scheme Reference

Hypothesis Colors

• Hypothesis 1: Deep Blue (RGB: 0, 102, 153) - Use for first hypothesis
• Hypothesis 2: Forest Green (RGB: 0, 128, 96) - Use for second hypothesis
• Hypothesis 3: Royal Purple (RGB: 102, 51, 153) - Use for third hypothesis
• Hypothesis 4: Teal (RGB: 0, 128, 128) - Use for fourth hypothesis (if needed)
• Hypothesis 5: Burnt Orange (RGB: 204, 85, 0) - Use for fifth hypothesis (if needed)

Utility Colors

• Predictions: Amber (RGB: 255, 191, 0) - For testable predictions
• Evidence: Light Blue (RGB: 102, 178, 204) - For supporting evidence
• Comparisons: Steel Gray (RGB: 108, 117, 125) - For critical comparisons
• Limitations: Coral Red (RGB: 220, 53, 69) - For limitations/challenges

Custom Box Environments

1. Executive Summary Box

\begin{summarybox}[Executive Summary]
  Content here
\end{summarybox}

Use for: High-level overview at the beginning of the document

---

2. Hypothesis Boxes (5 variants)

\begin{hypothesisbox1}[Hypothesis 1: Title]
  \textbf{Mechanistic Explanation:}
  [2-3 paragraphs explaining HOW and WHY]
  
  \textbf{Key Supporting Evidence:}
  \begin{itemize}
    \item Evidence point 1 \citep{ref1}
    \item Evidence point 2 \citep{ref2}
  \end{itemize}
  
  \textbf{Core Assumptions:}
  \begin{enumerate}
    \item Assumption 1
    \item Assumption 2
  \end{enumerate}
\end{hypothesisbox1}

Available boxes: hypothesisbox1, hypothesisbox2, hypothesisbox3, hypothesisbox4, hypothesisbox5

Use for: Presenting each competing hypothesis with its mechanism, evidence, and assumptions

Best practices for 4-page main text:

• Keep mechanistic explanations to 1-2 brief paragraphs only (6-10 sentences max)
• Include 2-3 most essential evidence points with citations
• List 1-2 most critical assumptions
• Ensure each hypothesis is genuinely distinct
• All detailed explanations go to Appendix A
• Use \newpage before each hypothesis box to prevent overflow
• Each complete hypothesis box should be ≤0.6 pages

---

3. Prediction Box

\begin{predictionbox}[Predictions: Hypothesis 1]
  \textbf{Prediction 1.1:} [Specific prediction]
  \begin{itemize}
    \item \textbf{Conditions:} When/where this applies
    \item \textbf{Expected Outcome:} Specific measurable result
    \item \textbf{Falsification:} What would disprove it
  \end{itemize}
\end{predictionbox}

Use for: Testable predictions derived from each hypothesis

Best practices for 4-page main text:

• Make predictions specific and quantitative when possible
• Clearly state conditions under which prediction should hold
• Always specify falsification criteria
• Include only 1-2 most critical predictions per hypothesis in main text
• Additional predictions go to appendices

---

4. Evidence Box

\begin{evidencebox}[Supporting Evidence]
  Content discussing supporting evidence
\end{evidencebox}

Use for: Highlighting key supporting evidence or literature synthesis

Best practices:

• Use sparingly in main text (detailed evidence goes in Appendix A)
• Include citations for all evidence
• Focus on most compelling evidence

---

5. Comparison Box

\begin{comparisonbox}[H1 vs. H2: Key Distinction]
  \textbf{Fundamental Difference:}
  [Description of core difference]
  
  \textbf{Discriminating Experiment:}
  [Description of experiment]
  
  \textbf{Outcome Interpretation:}
  \begin{itemize}
    \item \textbf{If [Result A]:} H1 supported
    \item \textbf{If [Result B]:} H2 supported
  \end{itemize}
\end{comparisonbox}

Use for: Explaining how to distinguish between competing hypotheses

Best practices:

• Focus on fundamental mechanistic differences
• Propose clear, feasible discriminating experiments
• Specify concrete outcome interpretations
• Create comparisons for all major hypothesis pairs

---

6. Limitation Box

\begin{limitationbox}[Limitations \& Challenges]
  Discussion of limitations
\end{limitationbox}

Use for: Highlighting important limitations or challenges

Best practices:

• Use when limitations are particularly important
• Be honest about challenges
• Suggest how limitations might be addressed

---

Document Structure

Main Text (Maximum 4 Pages - Highly Concise)

1. Executive Summary (0.5-1 page)

   • Use summarybox
   • Brief phenomenon overview
   • List all hypotheses in 1 sentence each
   • Recommended approach

2. Competing Hypotheses (2-2.5 pages)

   • Use hypothesisbox1, hypothesisbox2, etc.
   • One box per hypothesis
   • Brief mechanistic explanation (1-2 paragraphs) + essential evidence (2-3 points) + key assumptions (1-2)
   • Target: 3-5 hypotheses
   • Keep highly concise - details go to appendices

3. Testable Predictions (0.5-1 page)

   • Use predictionbox for each hypothesis
   • 1-2 most critical predictions per hypothesis only
   • Very brief - full predictions in appendices

4. Critical Comparisons (0.5-1 page)

   • Use comparisonbox for highest priority comparison only
   • Show how to distinguish top hypotheses
   • Additional comparisons in appendices

Main text total: Maximum 4 pages - be extremely selective about what goes here

Appendices (Comprehensive, Detailed)

Appendix A: Comprehensive Literature Review

• Detailed background (extensive citations)
• Current understanding
• Evidence for each hypothesis (detailed)
• Conflicting findings
• Knowledge gaps
• Target: 40-60+ citations

Appendix B: Detailed Experimental Designs

• Full protocols for each hypothesis
• Methods, controls, sample sizes
• Statistical approaches
• Feasibility assessments
• Timeline and resource requirements

Appendix C: Quality Assessment

• Detailed evaluation tables
• Strengths and weaknesses analysis
• Comparative scoring
• Recommendations

Appendix D: Supplementary Evidence

• Analogous mechanisms
• Preliminary data
• Theoretical frameworks
• Historical context

References

• Target: 50+ total references

Citation Best Practices

In Main Text

• Cite 15-20 key papers
• Use \citep{author2023} for parenthetical citations
• Use \citet{author2023} for textual citations
• Focus on most important/recent evidence

In Appendices

• Cite 40-60+ papers total
• Comprehensive coverage of relevant literature
• Include reviews, primary research, theoretical papers
• Cite every claim and piece of evidence

Citation Density Guidelines

• Main hypothesis boxes: 2-3 citations per box (most essential only)
• Main text total: 10-15 citations maximum (keep concise)
• Appendix A literature sections: 8-15 citations per subsection
• Experimental designs: 2-5 citations for methods/precedents
• Quality assessments: Citations as needed for evaluation criteria
• Total document: 50+ citations (vast majority in appendices)

Tables

Professional Table Formatting

\begin{hypotable}{Caption}
\begin{tabular}{|l|l|l|}
\hline
\tableheadercolor
\textcolor{white}{\textbf{Header 1}} & \textcolor{white}{\textbf{Header 2}} \\
\hline
Data row 1 & Data \\
\hline
\tablerowcolor  % Alternating gray background
Data row 2 & Data \\
\hline
\end{tabular}
\caption{Your caption}
\end{hypotable}

Best practices:

• Use \tableheadercolor for header rows
• Alternate \tablerowcolor for tables >3 rows
• Keep tables readable (not too wide)
• Use for quality assessments, comparisons

Common Formatting Patterns

Hypothesis Section Pattern

% Use \newpage before hypothesis box to prevent overflow
\newpage
\subsection*{Hypothesis N: [Concise Title]}

\begin{hypothesisboxN}[Hypothesis N: [Title]]

\textbf{Mechanistic Explanation:}

[1-2 brief paragraphs of explanation - 6-10 sentences max]

\vspace{0.3cm}

\textbf{Key Supporting Evidence:}
\begin{itemize}
  \item [Evidence 1] \citep{ref1}
  \item [Evidence 2] \citep{ref2}
  \item [Evidence 3] \citep{ref3}
\end{itemize}

\vspace{0.3cm}

\textbf{Core Assumptions:}
\begin{enumerate}
  \item [Assumption 1]
  \item [Assumption 2]
\end{enumerate}

\end{hypothesisboxN}

\vspace{0.5cm}

Note: The \newpage before the hypothesis box ensures it starts on a fresh page, preventing overflow. This is especially important when boxes contain substantial content.

Prediction Section Pattern

\subsection*{Predictions from Hypothesis N}

\begin{predictionbox}[Predictions: Hypothesis N]

\textbf{Prediction N.1:} [Statement]
\begin{itemize}
  \item \textbf{Conditions:} [Conditions]
  \item \textbf{Expected Outcome:} [Outcome]
  \item \textbf{Falsification:} [Falsification]
\end{itemize}

\vspace{0.2cm}

\textbf{Prediction N.2:} [Statement]
[... continue ...]

\end{predictionbox}

Comparison Section Pattern

\subsection*{Distinguishing Hypothesis X vs. Hypothesis Y}

\begin{comparisonbox}[HX vs. HY: Key Distinction]

\textbf{Fundamental Difference:}

[Description of core difference]

\vspace{0.3cm}

\textbf{Discriminating Experiment:}

[Experiment description]

\vspace{0.3cm}

\textbf{Outcome Interpretation:}
\begin{itemize}
  \item \textbf{If [Result A]:} HX supported
  \item \textbf{If [Result B]:} HY supported
  \item \textbf{If [Result C]:} Both/neither supported
\end{itemize}

\end{comparisonbox}

Spacing and Layout

Vertical Spacing

• \vspace{0.3cm} - Between elements within boxes
• \vspace{0.5cm} - Between major sections or boxes
• \vspace{1cm} - After title, before main content

Page Breaks and Overflow Prevention

CRITICAL: Prevent Content Overflow

LaTeX boxes (tcolorbox environments) do not automatically break across pages. Content that exceeds the remaining page space will overflow and cause formatting issues. Follow these guidelines:

1. Strategic Page Breaks Before Long Boxes:

\newpage  % Start on fresh page if box will be long
\begin{hypothesisbox1}[Hypothesis 1: Title]
  % Substantial content here
\end{hypothesisbox1}

2. Monitor Box Content Length:

   • Each hypothesis box should be ≤0.7 pages maximum
   • If mechanistic explanation + evidence + assumptions exceeds ~0.6 pages, content is too long
   • Solution: Move detailed content to appendices, keep only essentials in main text boxes

3. When to Use \newpage:

   • Before any hypothesis box with >3 subsections or >15 lines of content
   • Before comparison boxes with extensive experimental descriptions
   • Between major appendix sections
   • If less than 0.6 pages remain on current page before starting a new box

4. Content Length Guidelines for Main Text:

   • Executive summary box: 0.5-0.8 pages max
   • Each hypothesis box: 0.4-0.6 pages max
   • Each prediction box: 0.3-0.5 pages max
   • Each comparison box: 0.4-0.6 pages max

5. Breaking Up Long Content:

   % GOOD: Concise main text with page break
   \newpage
   \begin{hypothesisbox1}[Hypothesis 1: Brief Title]
   \textbf{Mechanistic Explanation:}
   Brief overview in 1-2 paragraphs (6-10 sentences).
   
   \textbf{Key Supporting Evidence:}
   \begin{itemize}
     \item Evidence 1 \citep{ref1}
     \item Evidence 2 \citep{ref2}
   \end{itemize}
   
   \textbf{Core Assumptions:}
   \begin{enumerate}
     \item Assumption 1
   \end{enumerate}
   
   See Appendix A for detailed mechanism and comprehensive evidence.
   \end{hypothesisbox1}
   

   % BAD: Overly long content that will overflow
   \begin{hypothesisbox1}[Hypothesis 1]
   \subsection{Very Long Section}
   Multiple paragraphs...
   \subsection{Another Long Section}
   More paragraphs...
   \subsection{Even More Content}
   [Content continues beyond page boundary → OVERFLOW!]
   \end{hypothesisbox1}
   

6. Page Break Commands:

   • \newpage - Force new page (recommended before long boxes)
   • \clearpage - Force new page and flush floats (use before appendices)

Section Spacing

Already handled by style package, but you can adjust:

\vspace{0.5cm}  % Add extra space if needed

Troubleshooting

Common Issues

Issue: "File hypothesis_generation.sty not found"

• Solution: Ensure the .sty file is in the same directory as your .tex file, or in your LaTeX path

Issue: Boxes don't have colors

• Solution: Compile with XeLaTeX or LuaLaTeX, not pdfLaTeX
• Command: xelatex yourfile.tex

Issue: Citations show as [?]

• Solution: Run bibtex after first xelatex compilation

xelatex yourfile.tex
bibtex yourfile
xelatex yourfile.tex
xelatex yourfile.tex

Issue: Fonts not found

• Solution: Comment out font lines in the .sty file if custom fonts aren't installed
• Lines to comment: \setmainfont{...} and \setsansfont{...}

Issue: Box titles overlap with content

• Solution: Add more vertical space with \vspace{0.3cm} after titles

Issue: Tables too wide

• Solution: Use \small or \footnotesize before tabular, or use p{width} column specs

Issue: Content overflowing off the page

• Cause: Boxes (tcolorbox environments) are too long to fit on remaining page space
• Solution 1: Add \newpage before the box to start it on a fresh page
• Solution 2: Reduce box content - move detailed information to appendices
• Solution 3: Break content into multiple smaller boxes
• Prevention: Keep each hypothesis box to 0.4-0.6 pages maximum; use \newpage liberally before boxes with substantial content

Issue: Main text exceeds 4 pages

• Cause: Boxes contain too much detailed information
• Solution: Aggressively move content to appendices - main text boxes should contain only:
  • Brief mechanistic overview (1-2 paragraphs)
  • 2-3 key evidence bullets
  • 1-2 core assumptions
• All detailed explanations, additional evidence, and comprehensive discussions belong in Appendix A

Package Requirements

Ensure these packages are installed:

• tcolorbox (with most option)
• xcolor
• fontspec (for XeLaTeX/LuaLaTeX)
• fancyhdr
• titlesec
• enumitem
• booktabs
• natbib

Install missing packages:

# For TeX Live
tlmgr install tcolorbox xcolor fontspec fancyhdr titlesec enumitem booktabs natbib

# For MiKTeX (Windows)
# Use MiKTeX Package Manager GUI

Style Consistency Tips

1. Color Usage

   • Always use the same color for each hypothesis throughout the document
   • H1 = blue, H2 = green, H3 = purple, etc.
   • Don't mix colors for the same hypothesis

2. Box Usage

   • Main text: Hypothesis boxes, prediction boxes, comparison boxes
   • Appendix: Can use evidence boxes, limitation boxes as needed
   • Don't overuse boxes - reserve for key content

3. Citation Style

   • Consistent citation format throughout
   • Use \citep{} for most citations
   • Group multiple citations: \citep{ref1, ref2, ref3}

4. Hypothesis Numbering

   • Number hypotheses consistently (H1, H2, H3, etc.)
   • Use same numbering in predictions (P1.1, P1.2 for H1)
   • Use same numbering in comparisons (H1 vs. H2)

5. Language

   • Be precise and specific
   • Avoid vague language ("may", "could", "possibly")
   • Use active voice when possible
   • Make predictions quantitative when feasible

Quick Checklist

Before finalizing your document:

• Title page has phenomenon name
• Main text is 4 pages maximum
• Executive summary is concise (0.5-1 page)
• Each hypothesis in its own colored box
• 3-5 hypotheses presented (not more)
• Each hypothesis has brief mechanistic explanation (1-2 paragraphs)
• Each hypothesis has 2-3 most essential evidence points with citations
• Each hypothesis has 1-2 most critical assumptions
• Predictions boxes with 1-2 key predictions per hypothesis
• Priority comparison box in main text (others in appendix)
• Priority experiments identified
• Page breaks (\newpage) used before long boxes to prevent overflow
• No content overflows off page boundaries (check PDF carefully)
• Each hypothesis box is ≤0.6 pages (if longer, move details to appendix)
• Appendix A has comprehensive literature review with detailed evidence
• Appendix B has detailed experimental protocols
• Appendix C has quality assessment tables
• Appendix D has supplementary evidence
• 10-15 citations in main text (selective)
• 50+ total citations in full document
• All boxes use correct colors
• Document compiles without errors
• References formatted correctly
• Compiled PDF checked visually for overflow issues

Example Minimal Document

% !TEX program = xelatex
\documentclass[11pt,letterpaper]{article}
\usepackage{hypothesis_generation}
\usepackage{natbib}

\title{Role of X in Y}

\begin{document}
\maketitle

\section*{Executive Summary}
\begin{summarybox}[Executive Summary]
Brief overview of phenomenon and hypotheses.
\end{summarybox}

\section{Competing Hypotheses}

% Use \newpage before each hypothesis box to prevent overflow
\newpage
\subsection*{Hypothesis 1: Title}
\begin{hypothesisbox1}[Hypothesis 1: Title]
\textbf{Mechanistic Explanation:}
Brief explanation in 1-2 paragraphs.

\textbf{Key Supporting Evidence:}
\begin{itemize}
  \item Evidence point \citep{ref1}
\end{itemize}
\end{hypothesisbox1}

\newpage
\subsection*{Hypothesis 2: Title}
\begin{hypothesisbox2}[Hypothesis 2: Title]
\textbf{Mechanistic Explanation:}
Brief explanation in 1-2 paragraphs.

\textbf{Key Supporting Evidence:}
\begin{itemize}
  \item Evidence point \citep{ref2}
\end{itemize}
\end{hypothesisbox2}

\section{Testable Predictions}

\subsection*{Predictions from Hypothesis 1}
\begin{predictionbox}[Predictions: Hypothesis 1]
Predictions here.
\end{predictionbox}

\section{Critical Comparisons}

\subsection*{H1 vs. H2}
\begin{comparisonbox}[H1 vs. H2]
Comparison here.
\end{comparisonbox}

% Force new page before appendices
\appendix
\newpage
\appendixsection{Appendix A: Literature Review}
Detailed literature review here.

\newpage
\bibliographystyle{plainnat}
\bibliography{references}

\end{document}

Key Points:

• \newpage used before each hypothesis box to ensure they start on fresh pages
• This prevents content overflow issues
• Main text boxes kept concise (1-2 paragraphs + bullet points)
• Detailed content goes to appendices

Additional Resources

• See hypothesis_report_template.tex for complete annotated template
• See SKILL.md for workflow and methodology guidance
• See references/hypothesis_quality_criteria.md for evaluation framework
• See references/experimental_design_patterns.md for design guidance
• See treatment-plans skill for additional LaTeX styling examples