reporting.instructions.md

applyTo	**/*
description	Reporting core contract (architecture-first, no code dumps)

Reporting Core Contract

This is the always-apply reporting contract. It is intentionally short to preserve working context.

Reports exist to align stakeholders on architecture and validation, not to duplicate implementation code.

When to produce reports

• Generate reports at key stages (especially Stage 1: Analysis) as described in code-change-phases.instructions.md, or when explicitly requested.

Where reports go

• Default location:
  • __reports__/<topic>/<round>-<descriptive_name>_v<version>.md
• Use __design__/ for durable architectural decisions.

Details (structure, naming, README conventions):

• reporting-structure.instructions.md

Content rules (architecture-first)

1) No code dumps

Reports must not include full implementations (no full modules/classes, no full function bodies).

Allowed:

• Signatures, schemas, pseudo-code, and small snippets strictly necessary to clarify a contract or invariant.

2) Default artifacts

• Architecture reports: Mermaid diagrams + contracts/invariants + alternatives + risks.
• Test definition reports: Risk-driven test matrix + fixtures strategy + minimal must-run regression set.

3) Keep reports reviewable

• Prefer tables, diagrams, and short sections.
• Avoid enumerating exhaustive permutations; use equivalence classes, boundary sets, and consolidation.

Specialized reporting guidance

• Architecture reporting guidance: reporting-architecture.instructions.md
• Test definition reporting guidance: reporting-tests.instructions.md
• Knowledge transfer (LLM cycle learnings): reporting-knowledge-transfer.instructions.md
• Templates: reporting-templates.instructions.md

Roadmaps (when needed)

If Stage 1 analysis reveals a complex multi-phase effort, prefer creating a formal roadmap directory tree in __roadmap__/ using:

• roadmap-generation.instructions.md