Common questions and answers about the Research Project Template
Quick Reference: Getting Started | Troubleshooting | How To Use
A: This is a template for research projects that provides a standardized structure with test-driven development, automated PDF generation, and professional documentation workflows. It's for academic papers, scientific documentation, technical reports, and any project requiring professional output.
A: Click the "Use this template" button on GitHub to create a new repository with this structure, then clone it and customize it for your project. The template includes everything you need to get started immediately.
A: The template is primarily designed for Python projects, but the documentation and PDF generation features work with any content. The core architecture focuses on Python with testing and build automation.
A: The structure follows the "thin orchestrator pattern" which separates business logic (src/) from orchestration (scripts/). This ensures maintainable, testable code while keeping scripts lightweight and focused on their specific tasks.
A:
projects/{name}/src/(Layer 2) contains business logic, algorithms, and mathematical implementations with robust test coverage.projects/{name}/scripts/are thin orchestrators that import use Layer 2 methods to generate specific figures, data, and outputs.scripts/(Layer 1 Root) are generic pipeline entry points that discover and execute the project-specificscripts/.
A: Coverage requirements are: 90% minimum for project code (currently achieving 100% - coverage!) and 60% minimum for infrastructure (currently achieving 83.33% - exceeds stretch goal!). The build pipeline enforces these to maintain professional standards.
A: The template uses Pandoc to convert markdown files to LaTeX, then XeLaTeX to generate PDFs. The ./run.sh entry point (or scripts/execute_pipeline.py) runs the full pipeline sequence: tests, analysis scripts, PDF rendering, validation, and copy-out, with optional LLM stages when not using --core-only. Stage layout is documented in RUN_GUIDE.md.
A: Yes! The LaTeX templates and Pandoc configurations can be customized. You can modify styles, add custom formatting, or even generate other formats like HTML or Word documents.
A: The template includes a cross-referencing system that automatically generates links between markdown files. See markdown-template-guide.md for detailed instructions.
A: You can remove the PDF-related utilities and focus on the core project structure. The template is modular, so you can use only the parts you need.
A: Test coverage ensures that your core business logic works correctly and remains reliable as you make changes. It's especially important for research projects where accuracy is critical.
A: Create test files in the projects/{name}/tests/ directory that follow the naming convention test_*.py. Use pytest fixtures and ensure your tests cover all code paths in your projects/{name}/src/ modules.
A: While pytest is the default, you can adapt the template to use other testing frameworks. Just update the build scripts and CI configuration accordingly.
A: Customize your project by editing projects/{name}/manuscript/config.yaml or setting environment variables (AUTHOR_NAME, PROJECT_TITLE, etc.). See Configuration Guide for details.
A: Absolutely! The template is designed to be extensible. You can add new output formats by creating new scripts and updating the build pipeline.
A: The template provides hooks and utilities that make it easy to integrate with CI/CD systems, documentation generators, and other development tools.
A:
- Ensure all tests pass with required coverage (90% project, 60% infra)
- Check that all required dependencies are installed
- Verify that your markdown files are properly formatted
- Check the build logs for specific error messages
A:
- Verify Pandoc and LaTeX are properly installed
- Check that your markdown syntax is correct
- Ensure all referenced figures and files exist
- Review the LaTeX templates for any syntax issues
A:
- Run tests with verbose output:
pytest projects/{name}/tests/ -v - Use pytest's debugging features:
pytest --pdb - Check coverage reports:
pytest projects/{name}/tests/ --cov=projects/{name}/src --cov-report=html - Review the test output for specific error messages
A: Yes! The template includes issue templates, pull request templates, and contribution guidelines that make collaboration easy and professional.
A: Fork the repository, make your improvements, and submit a pull request. See contributing.md for detailed guidelines.
A: Yes, the template is licensed under the Apache License 2.0, which allows commercial use, modification, and distribution.
A: Watch the repository for updates, check the repository releases and commit history, and consider contributing improvements back to the community.
A: The template includes 14 infrastructure modules: core (logging, config, pipeline, telemetry, exceptions), documentation (figure management, glossary), validation (output verification, integrity), publishing (academic workflows), scientific (scientific computing), llm (local LLM assistance, literature search), rendering (multi-format output), reporting (pipeline reporting and error aggregation), project (project discovery and orchestration), steganography (watermarking, provenance), config (configuration schemas and templates), docker (containerization), skills (SKILL.md discovery and Cursor manifest), and telemetry (unified pipeline resource and diagnostic tracking). See Modules Guide for documentation.
A: See the Modules Guide for usage examples and integration patterns. Each module includes API documentation and best practices.
A: API reference for all modules is available in API Reference, including function signatures, parameters, return values, and examples.
A: See .github/README.md for GitHub Actions setup, automated testing, and repository workflows.
A: Yes. Start with .github/workflows/README.md, then adapt workflows to run uv sync and the pipeline entry point you need (see RUN_GUIDE.md).
A: See the root README.md for uv install/sync commands, and use uv run to execute scripts consistently.
A: Start with uv lock --upgrade (if used in your workflow) and re-run uv sync. If conflicts persist, simplify optional groups and ensure project dependencies are represented in the root environment when running under the root venv (see docs/AGENTS.md).
A: See the Performance Optimization Guide for strategies to reduce build times, including parallel execution, caching, and optimization techniques.
A: See Performance Optimization Guide for measurement and tuning, and RUN_GUIDE.md for pipeline execution details.
A:
- Check the documentation in the docs/ directory
- Open an issue on GitHub for specific problems
- Review the examples and workflow guides
- Join the community discussions
For detailed documentation, see README.md, ../core/architecture.md, and ../core/workflow.md.
A: Yes! Use the feature request issue template to suggest improvements. We welcome all suggestions that would benefit the broader community.
Still have questions? Open an issue and we'll help you out! 🚀
For more information, see contributing.md and code-of-conduct.md.