Example Workflow
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines several key operational workflows defined within the project. These workflows provide structured, repeatable processes for common development tasks such as searching for information, conducting in-depth research, writing documentation, and making git commits. Adhering to these workflows ensures consistency, quality, and efficiency across the project.
The primary workflows covered include the multi-level Search Workflow, the rigorous Comprehensive Research Workflow, and the disciplined Git Commit Workflow. Each is designed to guide developers through a series of steps, from initial action to final output, while integrating with other project skills and tools.
Search Workflows
The project defines a multi-level approach to searching, allowing the process to scale based on the complexity of the query and the sufficiency of the results. The levels range from a simple, basic lookup to a comprehensive, multi-query investigation.
Sources: skills/search/references/examples/example-workflows.md
The following diagram illustrates the decision-making process for escalating through the search levels.
Search Levels Summary
The table below summarizes the trigger and actions for each search level.
| Level | Trigger | Key Actions |
|---|---|---|
| Level 1 | Simple lookup (e.g., "How to use React useState hook") | Basic Tavily search with search_depth: "basic" and maxResults: 5. |
| Level 2 | Insufficient results from Level 1 | Expand query, increase maxResults to 10, use search_depth: "advanced", and extract content from top URLs. |
| Level 3 | Repeated problem or best practices research | Run parallel queries, extract from top URLs of each, crawl relevant documentation, and synthesize a comprehensive understanding. |
Sources: skills/search/references/examples/example-workflows.md:5-26
Comprehensive Research Workflow
For tasks requiring deep, evidence-based decisions, the project specifies a comprehensive research workflow. This process is mandatory for all research tasks and emphasizes rigor, traceability, and context preservation. It integrates academic paper searches, non-academic source discovery, and critical evaluation to produce a final, actionable report.
Sources: skills/research/references/guides/guide-workflow.md:5-15, skills/research/SKILL.md:5-15
The overall workflow is broken down into several distinct steps, starting with understanding the existing codebase context.
Core Principle: The Write-First Pattern
A critical rule of the research workflow is the "Write-First Pattern". To prevent context overload and information loss due to limited context windows, evidence must be documented immediately after reading a small number of sources (1-2 maximum). This ensures knowledge is preserved in persistent evidence cards.
Sources: skills/research/references/guides/guide-workflow.md:7-12, skills/research/SKILL.md:17-24
The following diagram shows the mandatory incremental write-first loop.
Step 2: Comprehensive Discovery
This step involves a parallel search for both academic and non-academic sources, with a target of over 25 total sources to ensure broad coverage. The workflow also mandates "conflict-seeking" to find opposing viewpoints.
Sources: skills/research/references/guides/guide-workflow.md:60-84
Step 4: Generate Comprehensive Report
The final step is to synthesize all findings from the evidence cards into a report. This step explicitly requires re-reading the evidence cards and the original research question, but not the original papers, to avoid context overload.
Sources: skills/research/references/guides/guide-reports.md:10-16, skills/research/references/guides/guide-workflow.md:140-148
Git Commit Workflow
The project enforces a disciplined git commit workflow based on the "commit early, commit often" philosophy. Commits must be atomic, representing a single logical change, and should only be made when the code is in a working state (builds and tests pass).
Sources: skills/git-commit/SKILL.md:5-10
Feature Branch Workflow
The standard workflow for developing a feature involves creating a branch and making a series of small, incremental commits before creating a pull request.
Sources: skills/git-commit/SKILL.md:7-9
Commit Granularity
To maintain a clean and useful git history, changes should be grouped logically into separate commits.
| Commit Together (Same Commit) | Commit Separately (Different Commits) |
|---|---|
| A feature and its unit tests | A feature and an unrelated formatting change |
| A bug fix and its regression test | A bug fix and a dependency update |
| An API change and its documentation update | A refactor and a new feature |
| A refactor and updates to affected tests | Multiple unrelated fixes |
Sources: skills/git-commit/SKILL.md:86-92
Verification Before Committing
A key principle is to verify changes locally before committing. The "commit-and-pray" anti-pattern, where a developer commits untested code and relies on CI to find issues, leads to a broken and noisy git history.
The following sequence diagram illustrates the correct "verify-then-commit" workflow.
Sources: skills/git-commit/SKILL.md:124-133
Documentation Workflow
Workflows for writing and checking documentation are also defined. The docs-check skill analyzes code changes to suggest which documentation files may need updates, while the docs-write skill provides a structured process for creating or updating documentation according to project standards.
Sources: skills/docs-check/SKILL.md:16-21, skills/docs-write/SKILL.md:12-15
The documentation writing process is guided by the documentation-guide.md reference file, which specifies the type of document to create (Tutorial, How-to, Reference, or Explanation).
Sources: skills/docs-write/SKILL.md:18-24, skills/docs-write/references/documentation-guide.md:38-42
Conclusion
The defined workflows for searching, research, committing, and documentation form a foundational part of the development process in this repository. They promote a systematic, evidence-based, and quality-driven approach. By following these structured processes, developers can ensure their contributions are robust, maintainable, and well-documented.