Goga Review Cell

Cell Review

Purpose

Reviews a cell across three dimensions and proposes concrete remediation actions for each detected issue. Each action requires explicit user confirmation before execution.

You identify issues, propose solutions, and execute user-approved actions (invoking other skills, editing files).

Key Principle

Identify the exact problem before proposing a solution. The three review dimensions target distinct root causes and require different remediation strategies. Do not conflate them — classify each finding into exactly one of the three categories before proposing any action.

User Interaction Rule

Always provide answer options. When requesting user confirmation, decisions, or clarifications, always offer 2–4 concrete options to choose from. Never pose open-ended questions without selectable choices.

Steps

Step 1: Load Context

1. Invoke goga-lang-disp via the Skill tool to load the target language skill. The language skill defines implementation conventions: cell structure, facade, signature rules, naming. Examples in other skills may follow naming conventions of one language (e.g., snake_case), while the target language requires different conventions (e.g., PascalCase). The language skill contains authoritative rules for the target language.
2. Load the DSL specification and DSL application principles:
   • Invoke goga-cell via the Skill tool to understand CODEMANIFEST DSL syntax, structural rules, and semantics (cell structure, Imports, Usages, Annotations directives, types, signatures, mutations, embeddings, constraints)
   • Invoke goga-cookbook via the Skill tool to understand cell and CODEMANIFEST working principles (when to use Entity vs Routine, when to apply mutations and embeddings, usage file authoring principles, cell granularity)
   • Critical for accurate analysis: without understanding DSL rules, CODEMANIFEST entries will be misinterpreted
   • Consult the loaded specification and principles whenever CODEMANIFEST entry correctness is uncertain
3. Read the cell's CODEMANIFEST file
4. Parse all entities, methods, properties, imports, usages, annotations, re-exports, and locations
5. Enumerate all source files in the cell directory (excluding .usages/, build artifacts, tests, and other non-contract files)
6. Read all source files corresponding to declared location values
7. Read all .usages/*.md files if the .usages/ directory exists
8. Verify the facade file exists

Step 2: Run Tools

2a. Run Linter

goga lint

If the linter reports errors, record each as a DSL syntax issue. Fix all DSL syntax errors before proceeding with analysis.

2b. Run Schema

goga schema

Extract the cell's position in the project hierarchy for contextual reference.

Step 3: Analysis 1 — Code vs Requirements

Question: Does the code implement what CODEMANIFEST requires?

For each entity declared in CODEMANIFEST, verify that the implementation satisfies the contract.

3a. Checks

For each entity:

• Signature conformance: Compare "()" (constructor signature) between CODEMANIFEST and source code
• Method coverage: Compare the "methods" dictionary — identify missing, extra, or mismatched method signatures
• Property coverage: Compare the "properties" dictionary — identify missing, extra, or mismatched property types
• Facade exposure: Verify the entity appears on both sides. Absence in source code means it is not exported via the facade

For each function (routine):

• Signature conformance: Compare the signature string between CODEMANIFEST and source code
• Existence: Absence in source code means the function is not exported via the facade

Additional checks:

• Location validity: Does the source file exist at path <cell-path>/<location>?
• Behavioral conformance: Does the implementation satisfy behavioral requirements from annotations?
• Import utilization: Are imported types from Imports actually referenced in source code?

3b. Findings Presentation

When issues are detected, present each finding with:

• Exact location (entity, method/property, file)
• What CODEMANIFEST requires vs. what the code actually does

3c. Proposed Action

Formulate a task describing the discrepancy between code and contract.

Propose: invoke /goga:design in brainstorm mode, passing the task as context. This produces an implementation redesign that satisfies the contract.

Request user confirmation before execution.

Step 4: Analysis 2 — Requirements vs Code and Usages

Questions: Do CODEMANIFEST requirements match the actual code and usages? Is CODEMANIFEST well-authored?

The contract may be incomplete, incorrect, outdated, or poorly written compared to what the code actually implements and what usages describe.

4a. Checks: Accuracy

• Undocumented entities: Are there public classes/functions in the code not declared in CODEMANIFEST?
• Undocumented methods/properties: Are there public API members of documented classes missing from CODEMANIFEST?
• Contract accuracy vs usages: Do annotations reference actually applicable usages? Are usages used in code but not mentioned in annotations?
• Requirements accuracy: Do described signatures, types, and behaviors match what the code actually does? If the code is correct and the contract is wrong — the contract requires correction.

4b. Checks: Authoring Quality

For each entity and function (routine) in CODEMANIFEST, verify that annotations satisfy the following authoring quality criteria. Even a technically correct contract degrades overall quality when annotations are poorly written.

Content guidelines:

• Begin each annotation with a clear purpose statement — what this entity/function/method does and why it exists
• For each parameter, provide a description using `parameter_name`: description syntax
• For non-trivial logic (multi-step transformations, conditional flows, state transitions), include an Algorithm: section with numbered steps tracing the execution flow
• For constraints, edge cases, format requirements, or preconditions — include a Requirements: section with explicit descriptions
• Document return value format when semantics are non-obvious from the signature (e.g., when meaning differs from type or structure is complex)
• Include usage examples when they help clarify the contract — configuration examples for builders, input/output pairs for parsers, invocation patterns for facades

Quality guidelines:

• Each annotation must be specific enough for direct implementation — no TBD, TODO, or vague phrasing
• Each annotation must permit exactly one interpretation — if ambiguous, rewrite it
• Maintain consistent style and structure across all annotations within a single CODEMANIFEST file
• All backtick references (`name`) must resolve to entities in the current CODEMANIFEST context — types from Imports, practices from Usages, or parameters from the signature

4c. Findings Presentation

When issues are detected, present each finding with:

• Exact CODEMANIFEST location (entity, method/property, section)
• Nature of the issue: missing declaration, inaccurate description, incorrect type, outdated reference, poor annotation quality
• For authoring quality issues: a specific improvement recommendation (e.g., "add Algorithm: section", "describe parameter path", "restructure annotation with Algorithm: and Requirements: sections")

4d. Proposed Action

Edit CODEMANIFEST to correct inaccuracies and improve authoring quality, then invoke /goga:design in changes mode to update the design document based on the corrected contract.

Request user confirmation before execution.

Step 5: Analysis 3 — Usage Existence and Adequacy

Question: Do usage files exist and are they adequate for the cell implementation?

5a. Checks

• Existence: For each Usages entry with a file path — does the file exist? (project-level in .goga/usages/, cell-level in .usages/ directory)
• Annotation reference: Is each declared usage referenced in an annotation via backtick syntax?
• Imported usage existence: For each imported usage from Imports → Usages — does {from_path}/.usages/{usage_name}.md exist?
• Adequacy: Does each .usages/*.md file describe cell API usage? Is the content accurate and sufficiently detailed for consumers?
• Missing usages: Are there external library imports, recurring patterns, or code conventions not covered by any Usages entry?
• Categorization: Are .usages/ functional categories clearly defined and non-overlapping? Should inline usages be extracted into category files?

5b. Findings Presentation

When issues are detected, present each finding with:

• Which usage is missing, outdated, or inadequate
• What practice it should describe

5c. Proposed Action

Create or update .usages/*.md files directly. This does not require invoking another command — usage files are practice documentation editable directly.

Request user confirmation before execution.

Step 6: Execute Approved Actions

For each user-approved action across all three analyses:

6a. Code vs Requirements (Step 3)

1. Formulate a clear redesign task description
2. Invoke /goga:design and select brainstorm mode
3. Pass the task as context — the design skill will handle the redesign

6b. Requirements vs Code/Usages (Step 4)

1. Apply CODEMANIFEST edits directly
2. Run linter for validation: goga lint
3. Fix all DSL syntax errors after edits
4. Invoke /goga:design and select changes mode
5. The design skill will detect changes via git diff and update the document accordingly

6c. Usages (Step 5)

1. Create or update the corresponding .usages/*.md files
2. Ensure content accurately describes cell API usage with sufficient detail for consumers (implementation details may be present but are secondary)

6d. Final Validation

After executing all approved actions (6a, 6b, 6c):

1. Run linter for final validation: goga lint
2. If the linter reports errors — fix them
3. Repeat steps 1–2 until the linter passes without errors

Result

• Review findings across all three dimensions
• Analysis 1 (Code vs Requirements): task delegated to /goga:design brainstorm
• Analysis 2 (Requirements vs Code/Usages): CODEMANIFEST edits + /goga:design changes
• Analysis 3 (Usages): created or updated .usages/*.md files

Final Self-Check

Before completion, verify:

1. Was the DSL specification loaded via goga-cell and goga-cookbook skills before analysis?
2. Was the cell's CODEMANIFEST fully parsed?
3. Were all source files verified against the contract?
4. Were all .usages/ files analyzed?
5. Was goga lint executed?
6. Was goga schema executed?
7. Was Analysis 1 (Code vs Requirements) completed with clear findings and a proposed action?
8. Was Analysis 2 (Requirements vs Code/Usages) completed with both accuracy and authoring quality checks?
9. Was Analysis 3 (Usage Existence and Adequacy) completed with clear findings and a proposed action?
10. Was each finding classified into the correct analysis category before proposing an action?
11. Were all actions confirmed by the user before execution?
12. Were approved actions executed correctly?
13. Was goga lint executed after all actions and did it pass without errors?

If any answer is "no" — complete the outstanding work before returning.