Skip to content

reporting.instructions.md

Latest commit

 

History

History
287 lines (197 loc) · 10.1 KB

reporting.instructions.md

File metadata and controls

287 lines (197 loc) · 10.1 KB
Raw
file_type instructions
title Reporting Instructions
description Guidelines for generating and storing reports in this repository.
version 1.1
last_updated 2025-12-08
owners
LightSpeed Engineering
tags
reporting
automation
governance
standards

Reporting Instructions

You are a reporting governance assistant. Follow our reporting standards to generate, name, and store artefacts under the correct .github/reports categories. Avoid placing outputs in root or docs/, using non-kebab-case names, or skipping required metadata.

Overview

Applies to all report outputs (Markdown, JSON, CSV, HTML) created by contributors or agents. Covers locations, naming, categories, and examples. Excludes permanent docs (use docs/ per file-organisation rules).

General Rules

  • Store reports under .github/reports/{category}/ with kebab-case names and dates/versions.
  • Never store reports in repo root, docs/, or /tmp/ (except transient processing).
  • Align categories with purposes and follow naming patterns.
  • Do not add a references front matter field to report docs; use inline links or the footer to cite supporting resources.

Detailed Guidance

This document outlines where various reports generated by our scripts and workflows should be stored. See sections below for general rules, category references, and naming conventions.

Examples

  • Good: .github/reports/analysis/code-complexity-analysis-2025-12-08.md or .github/reports/progress/weekly-summary-2025-w50.md.
  • Avoid: report.txt in repo root or docs/ without category/date.

Validation

  • Check report paths and filenames against mapping before committing.
  • Confirm categories match report purpose and include dates where applicable.
  • Ensure transient processing files are cleaned up or promoted correctly.

1. General Rules

  • Location: All reports must be stored in a relevant subfolder within .github/reports/.
  • Naming: All filenames must be kebab-case and include a date or version where applicable.

Reporting Standards & Conventions

Purpose

Provide a single source of truth for creating, formatting, and storing reports, with specific guidance for daily updates and weekly summaries on long-running projects.

Scope

Applies to all report-like outputs (Markdown, JSON, CSV, HTML) created by contributors or agents. These rules sit alongside file-organisation and community standards.

Locations

  • Canonical path: .github/reports/{category}/
  • Progress tracking: use .github/reports/progress/ for multi-day or multi-week project updates.
  • Never place reports in repository root, docs/, or /tmp/ (except transient processing).

Naming

  • Kebab-case filenames; avoid spaces and uppercase.
  • Prefer descriptive names with ISO dates for time-bound updates.
  • Progress examples:
    • .github/reports/progress/daily-update-2025-12-11.md
    • .github/reports/progress/weekly-summary-2025-w50.md

2. Report Category Reference

This section details the purpose of each report category and the required file naming conventions.

/agents

Purpose: Logs and outputs from AI agent executions, agent infrastructure audits, agent performance reports, and any documentation about agent implementations or fixes. File Naming: {agent-name}-{task-id}-{YYYY-MM-DD}.{log|md|json} Examples:

  • labeling-agent-pr-123-2025-12-08.log
  • agent-infrastructure-audit-2025-12-10.md
  • critical-agent-fixes-2025-12-10.md

Important: Reports about agents (audits, infrastructure reviews, agent fixes) belong here, not in /audits or /implementation. The /agents category captures both agent execution outputs and meta-documentation about the agent system itself.

/analysis

Purpose: In-depth analysis of code, architecture, or processes. File Naming: {topic}-analysis-{YYYY-MM-DD}.{md|json} Example: code-complexity-analysis-2025-12-08.md

/audits

Purpose: One-time audit reports for security, accessibility, or compliance. File Naming: {audit-type}-audit-{YYYY-MM-DD}.{md|csv|json} Example: security-audit-2025-12-08.md

/coverage

Purpose: Code coverage reports generated from test runs. File Naming: coverage-report-{workflow-run-id}.{json|lcov} Example: coverage-report-12345.json

/frontmatter

Purpose: Reports from frontmatter validation and audit scripts. File Naming: frontmatter-audit-{YYYY-MM-DD}.{csv|md} Example: frontmatter-audit-2025-12-08.csv

/implementation

Purpose: Tracking reports for the implementation of features or epics. File Naming: implementation-plan-{feature-name}.md Example: implementation-plan-user-auth.md

/issue-metrics

Purpose: Metrics related to GitHub issues (e.g., time to close, label distribution). File Naming: issue-metrics-{YYYY-MM}.md Example: issue-metrics-2025-12.md

/labeling

Purpose: Reports from the automated labeling agent. File Naming: labeling-report-pr-{pr-number}.md Example: labeling-report-pr-123.md

/linting

Purpose: Reports from code linters (ESLint, Stylelint, etc.). File Naming: {linter}-report-{YYYY-MM-DD}.{txt|json} Example: eslint-report-2025-12-08.json

/mermaid

Purpose: Mermaid diagram reports — coverage of required diagrams, accessibility/contrast audits (WCAG AA), rendering checks, and update tracking. File Naming: mermaid-{subject}-{YYYY-MM-DD}.{md|csv|json} Examples:

  • mermaid-coverage-audit-2025-12-12.md
  • mermaid-contrast-checks-2025-12-12.csv
  • mermaid-readme-updates-2025-12-12.json

/meta

Purpose: Reports from the meta agent, which manages badges, footers, and other metadata. File Naming: meta-agent-run-{YYYY-MM-DD}.log Example: meta-agent-run-2025-12-08.log

/metrics

Purpose: General repository and developer workflow metrics. File Naming: repo-metrics-{YYYY-MM}.md Example: repo-metrics-2025-12.md

/migration

Purpose: Reports related to data, schema, or platform migrations. File Naming: migration-status-{migration-name}-{YYYY-MM-DD}.md Example: migration-status-db-schema-v2-2025-12-08.md

/optimisation

Purpose: Reports on performance and resource optimisation efforts. File Naming: optimisation-report-{area}-{YYYY-MM-DD}.md Example: optimisation-report-webpack-bundle-2025-12-08.md

/tech-debt

Purpose: Reports tracking identified technical debt. File Naming: tech-debt-summary-{YYYY-MM}.md Example: tech-debt-summary-2025-12.md

/validation

Purpose: Reports from validation scripts (e.g., schema validation, link checking). File Naming: {validation-type}-validation-{YYYY-MM-DD}.{md|json} Example: schema-validation-2025-12-08.json

Frontmatter (Markdown reports)

Include at minimum:

---
title: "Concise report title"
description: "1–2 sentence summary"
file_type: "report"
category: "progress" # or other category
created_date: "YYYY-MM-DD"
version: "v1.0.0"
authors: ["name or automation"]
tags: ["progress", "weekly-summary"]
references:
  - path: ".github/projects/{related-file}.md"
    description: "Related project tracker"
---

Progress Tracking Templates

Daily Update (per day)

## Date: YYYY-MM-DD
**Work Completed**:
- Task X.Y completed
- N tests added to file.test.js
- Coverage increased from X% to Y%

Guidance:

  • One file per day when detail matters, or append to a weekly summary file for brevity.
  • Keep bullets action-focused; quantify changes (tests, coverage, tickets closed).

Weekly Summary (week ending or ISO week)

## Week of YYYY-MM-DD
**Summary**:
- Phase X completed
- Coverage: X% → Y% (Δ+Z%)
- Tests added: N

**Key Achievements**:
- [List achievements]

**Challenges**:
- [List challenges]

**Blockers**:
- None / [describe blocker]

**Next Steps**:
- Continue with Task X.Y+1

Guidance:

  • Use one file per week per project (e.g., weekly-summary-2025-w50.md).
  • Link back to related project trackers in .github/projects/.
  • Capture blockers clearly; propose mitigation if known.

Folder Rules

  • Create .github/reports/progress/ if absent; keep daily and weekly files here.
  • Do not mix progress reports into metrics/ or implementation/; use progress/ for chronological updates.
  • Update .github/reports/README.md when adding new categories or conventions.

Quality & Review

  • Ensure accessibility (clear headings, meaningful link text) and performance (avoid oversized embeds).
  • Run lint/format for Markdown if configured; fix frontmatter schema issues.
  • If coverage or test counts change, note whether metrics are project-wide or scoped.

Checklist (before committing)

  • Stored under .github/reports/{category}/ with kebab-case filename.
  • Frontmatter present and valid; category set to progress for updates.
  • Daily/weekly template followed; metrics and blockers captured.
  • Related project/report indexes updated if structure changed.

References

Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team Org Profile

Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team Org Profile

Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team Org Profile

Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team Org Profile

Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team Org Profile

Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team Org Profile