Output Data Structure
Relevant source files
The following files were used as context for generating this wiki page:
- skills/research/references/templates/template-evidence-card.md
- skills/research/references/templates/template-research-question.md
- skills/research/references/guides/guide-reports.md
- skills/docs-write/references/documentation-guide.md
- skills/git-commit/references/examples.md
- skills/docs-check/scripts/check-docs.sh
- skills/research/references/guides/guide-workflow.md
The ai-dev-atelier project defines several standardized output data structures to ensure consistency across different development activities, such as research, documentation, and version control. These structures are primarily defined through Markdown templates and guides, which govern the format of research artifacts, API documentation, and git commit messages.
This document outlines the key output structures, their components, and the relationships between them. The primary goal is to provide a clear and consistent format for information, making it more discoverable, machine-readable, and easier for developers to consume.
Research Skill Output Structure
The research skill produces a set of interconnected Markdown files and a JSON manifest to capture the entire research process, from the initial question to the final report. The structure is designed to be incremental and traceable.
Sources: skills/research/references/guides/guide-workflow.md, skills/research/references/guides/guide-reports.md, skills/research/references/templates/template-evidence-card.md
Research Artifact Relationship
The following diagram illustrates the relationship between the different artifacts generated during the research workflow. A central references.json file tracks all entities.
Research Question (research-question.md)
This file initiates the research process and grounds it in the project's context.
| Section | Description |
|---|---|
| Codebase Context | Documents the current architecture, technologies, and relevant files to ensure research is applicable. |
| Research Question | The specific problem statement to be investigated. |
| Context / Background | Explains why the research is needed. |
| Desired Outcome | Defines the goals of the research (e.g., make a decision, understand a concept). |
| Constraints | Lists any technical or business constraints (e.g., performance, scalability, existing tech stack). |
Sources: skills/research/references/templates/template-research-question.md
Evidence Card (evidence-card-*.md)
An evidence card synthesizes information from multiple academic and non-academic sources about a single, specific approach. At least five evidence cards are required for comprehensive research.
| Section | Description |
|---|---|
| Approach Overview | A high-level summary of the approach. |
| Papers/Sources | A list of academic papers and non-academic sources supporting the approach, including metadata and weighting (High, Medium, Low). |
| Key Claims | 3-5 synthesized, actionable claims demonstrated by the sources. |
| Supporting Evidence | Direct quotes from sources, organized by claim, with page numbers and context. |
| Assumptions/Conditions | The prerequisites and assumptions under which the approach is valid. |
| Tradeoffs / Limitations | The downsides and what is gained versus lost. |
| Failure Modes | Scenarios where the approach is known to fail. |
| Related Approaches | Links to other evidence cards, noting conflicts, complements, or alternatives. |
| Implementation Resources | A list of packages, libraries, tutorials, and code examples for practical application. |
Sources: skills/research/references/templates/template-evidence-card.md, skills/research/references/evidence-card-guide.md:19-32
Research Report (research-report.md)
The final output that synthesizes all evidence cards into a comparative analysis with actionable recommendations.
| Section | Description |
|---|---|
| Executive Summary | A 2-3 paragraph overview of the findings and primary recommendation. |
| Research Methodology | Documents the search strategy, selection criteria, and approach grouping. |
| Approaches Compared | A detailed section for each evidence card. |
| Comparative Analysis | Side-by-side tables comparing the strengths, limitations, and best-fit scenarios for each approach. |
| Evidence Summary | Highlights supporting, conflicting, and missing evidence across all sources. |
| Recommendations | Provides a primary recommendation for the general case and alternative recommendations for specific scenarios. |
| Answer to Original Question | Explicitly addresses the initial research question with evidence-backed conclusions. |
Sources: skills/research/references/guides/guide-reports.md:25-156
Documentation Output Structure
The project mandates a "docs-as-code" approach with standardized structures for API documentation, database schemas, and architectural overviews.
Sources: skills/docs-write/references/documentation-guide.md
API Endpoint Documentation
API endpoints are documented with a consistent structure that includes request/response examples and error codes.
Sources: skills/docs-write/references/documentation-guide.md:200-225
An example structure for a POST /api/posts endpoint is as follows:
### Create Post
`POST /api/posts`
#### Request:
```json
{
"title": "My Post",
"content": "Post content"
}
Response:
{
"id": "uuid",
"title": "My Post",
"created_at": "2025-01-15T10:30:00Z"
}
Errors:
400 Bad Request- Invalid title or content401 Unauthorized- Missing or invalid authentication
This structure ensures that consumers of the API have clear, runnable examples and can anticipate error conditions.
### Database Schema Documentation
Database documentation is expected to be concise and visual. It combines a brief textual overview with a more detailed diagram.
The recommended structure includes:
1. A list of core tables and their purpose.
2. A link to a detailed Entity Relationship Diagram, preferably using Mermaid for inline rendering or a separate `.puml` file for PlantUML.
*Sources: [skills/docs-write/references/documentation-guide.md:189-198](https://github.com/LukasStrickler/ai-dev-atelier/blob/HEAD/skills/docs-write/references/documentation-guide.md#L189-L198), [skills/docs-write/references/documentation-guide.md:108-122](https://github.com/LukasStrickler/ai-dev-atelier/blob/HEAD/skills/docs-write/references/documentation-guide.md#L108-L122)*
This diagram shows an example of an inline Mermaid ER diagram for a simple schema.
Git Commit Message Structure
The repository follows the Conventional Commits specification to create an explicit commit history. This structured format makes commits easier to understand and allows for automated processing.
Sources: skills/git-commit/references/examples.md
Conventional Commit Format
The basic structure of a commit message is as follows:
<type>(<scope>): <subject>
[optional body]
[optional footer]
The following diagram breaks down the components of a conventional commit message.
| Component | Description | Example |
|---|---|---|
| type | Describes the kind of change (e.g., feat, fix, docs, refactor). | feat |
| scope | An optional noun describing the section of the codebase affected. | (api) |
| subject | A short, imperative-tense description of the change. | add dark mode toggle |
| body | An optional, more detailed explanation of the changes. | Persists preference to localStorage. |
| footer | Optional section for metadata, such as referencing issues (Closes #142) or noting breaking changes. | BREAKING CHANGE: ... |
Sources: skills/git-commit/references/examples.md
Docs Check Script Output
The docs-check.sh script produces a structured text output that analyzes code changes and suggests which documentation files may need to be updated. The output is categorized by the type of code change detected.
Sources: skills/docs-check/scripts/check-docs.sh
Output Flow
The script follows this logic to generate its report:
- It computes the
git diffagainst the main branch to find all changed files. - It separates changed files into code and documentation.
- It categorizes code changes based on file path and name patterns (e.g.,
api,schema,component). - For each category, it prints the changed files and suggests relevant documentation to review.
An example output snippet for API changes:
â ď¸ API changes detected:
- src/api/router/posts.ts
đ Check these documentation files:
- .docs/api/endpoints.md
- .docs/workflow/process.md
- README.md
Sources: skills/docs-check/scripts/check-docs.sh:130-149
Conclusion
The ai-dev-atelier repository emphasizes structured, template-driven outputs for its core development processes. For research, a series of interconnected artifacts ensures traceability and comprehensive analysis. For documentation, consistent formats for APIs and schemas improve clarity and usability. Finally, for version control, conventional commits provide a machine-readable and human-friendly history of changes. These standardized data structures are fundamental to the project's goals of consistency, automation, and maintainability.