goga-review-design

Design Review

Purpose

Verifies the design document (the file at the path printed by goga history path -f design.md) for logical correctness by tracing the full code stack for each entry point and test scenario. This is a verification pass — the goal is to find logical errors before plan creation.

You do not write implementation code. You trace each logical chain and find where the logic breaks.

---

Core Principle

Trace, do not assume. For each logical chain, mentally execute the code path step by step. Read actual source files and library documentation to verify correctness. If a step cannot be verified due to missing information — that in itself is a remark.

User Interaction Rule

Always offer answer choices. When requesting a user decision or confirmation — always provide 2–4 concrete options. Never ask open-ended questions without selectable choices.

CODEMANIFEST Editing

When tracing reveals errors in the contract itself (not in the design's interpretation of the contract), you must propose CODEMANIFEST edits. These are not design-level remarks — they are contract-level errors that block correct implementation regardless of design structure.

Conditions requiring CODEMANIFEST editing:

• Insufficient requirements: missing type declarations, incomplete signatures, absent method/property descriptions
• Contradictory requirements: contradictions between entity interfaces, type mismatches between interacting entities
• Contract interaction errors: broken type chains between interfaces, Type:: mutations referencing non-existent or incompatible types, interface contracts diverging in data formats

All CODEMANIFEST edits must be proposed to the user before applying.

---

Phases

Phase 1: Context Loading

1. Load the DSL specification and DSL application principles:
   • Use the Skill tool to invoke goga-cell — for understanding CODEMANIFEST DSL rules before reviewing contracts (document structure, signature syntax, Imports rules, Usages rules, Annotations rules, types, mutations, embeddings, constraints)
   • Use the Skill tool to invoke goga-cookbook — for understanding cell design principles and CODEMANIFEST (when to use Entity vs Routine, when to apply mutations and embeddings, usage file authoring principles, cell granularity)
2. Read the design document from the path printed by goga history path -f design.md
3. Read all relevant CODEMANIFEST files referenced by the design
4. Read existing source files referenced by the design (if any)
5. Execute goga schema --help to understand the command, then execute goga schema to obtain the full project dependency graph. Use --depends-on <cell_path> to discover cells that depend on cells modified by the design. This ensures the review covers all affected cells.
6. Reading Usage specifications by reference: determine which Usages to read based on references:
   • Always read root Usages — Usages (files from .goga/usages/) referenced by global Annotations in the CODEMANIFEST header (via backtick syntax) are always read
   • Always read Usages of modified entities — for each entity covered by the design, scan its annotations for references (backticks) to Usages. All referenced Usages are read
   • Skip unreferenced Usages — Usage entries not referenced by global Annotations AND not referenced by annotations of any covered entity are skipped