{"slug":"goga-review-arch","title":"goga-review-arch","summary":"Review an architecture plan for semantic correctness","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-24T17:38:12.681315Z","repo":{"url":"https://github.com/qarium/goga","stars":31,"forks":0,"license":"BSD-3-Clause","updatedAt":"2026-09-18T23:57:35Z"},"bodyHtml":"<hr>\n<h2>name: goga-review-arch\ndescription: Review an architecture plan for semantic correctness</h2>\n<h1>Architecture Review</h1>\n<h2>Objective</h2>\n<p>Validate the architecture plan (<code>docs/arch/&lt;topic&gt;.md</code>) for <strong>semantic correctness</strong> — assess model cohesion, domain boundary\nsoundness, and requirement sufficiency for implementation.\nThe agent <strong>analyzes</strong> the architecture plan, <strong>reports</strong> findings, and <strong>applies fixes</strong> when issues are detected\n(subject to user approval).</p>\n<hr>\n<h2>Core Principle</h2>\n<p><strong>Architecture is a cohesive system, not a collection of isolated contracts.</strong> The agent validates the interaction across\nall types, domains, and requirements as a unified whole — not each CODEMANIFEST in isolation.</p>\n<hr>\n<h2>Input</h2>\n<ul>\n<li><strong>Required</strong>: architecture plan at <code>docs/arch/&lt;topic&gt;.md</code></li>\n<li><strong>Optional</strong>: task file at <code>docs/tasks/&lt;topic&gt;.md</code> — when present, used to verify requirements coverage</li>\n</ul>\n<hr>\n<h2>Phases</h2>\n<h3>Phase 1: Context Loading</h3>\n<ol>\n<li>Read the architecture plan from <code>docs/arch/&lt;topic&gt;.md</code></li>\n<li>Load the DSL specification and DSL application principles:\n<ul>\n<li>Invoke <code>goga-cell</code> via <strong>Skill tool</strong> — to understand DSL rules\n(signature syntax, Import/Usage/Annotation rules, types, mutations, embeddings, constraints)</li>\n<li>Invoke <code>goga-cookbook</code> via <strong>Skill tool</strong> — to understand cell and CODEMANIFEST design principles\n(Entity vs Routine selection criteria, when to apply mutations and embeddings, usage file authoring guidelines,\ncell granularity)</li>\n</ul>\n</li>\n<li>Load language-specific implementation rules:\n<ul>\n<li>Invoke <code>goga-lang-disp</code> via <strong>Skill tool</strong> — to obtain the target language skill.\nThe language skill defines implementation conventions: cell structure, facade pattern, signature rules, <strong>naming</strong>.\nExamples in other skills may follow naming conventions of one language (e.g., snake_case), whereas the target\nlanguage requires another (e.g., PascalCase) — the language skill is the authoritative source for the target language.</li>\n</ul>\n</li>\n<li>Invoke <code>goga-codemanifest-base</code> via <strong>Skill tool</strong> — to obtain the project's baseline usages and annotations</li>\n<li>Retrieve the current project schema:\n<ul>\n<li>Run <code>goga schema</code> to obtain the existing cell hierarchy</li>\n<li>Classify plan cells: newly created vs. modified</li>\n</ul>\n</li>\n<li>Read the existing CODEMANIFESTs of cells the plan marks for modification</li>\n<li>Read the existing <code>.usages/</code> files of cells marked for modification</li>\n<li>If the task file <code>docs/tasks/&lt;topic&gt;.md</code> exists — read it for subsequent requirements coverage verification</li>\n</ol>\n<hr>\n<h3>Phase 2: Plan Structure Validation</h3>\n<p>Verify the architecture plan contains <strong>all mandatory sections</strong>:</p>\n<ol>\n<li><strong>Implementation order</strong> — cells sequenced with rationale for ordering</li>\n<li><strong>Artifacts per cell</strong> — CODEMANIFEST and <code>.usages/</code> files</li>\n<li><strong>Dependency map</strong> — ASCII diagram or enumerated cell-to-cell connections</li>\n<li><strong>Verification checklist</strong> — post-implementation validation criteria</li>\n</ol>\n<p>If any section is missing — log as a <strong>Critical</strong> finding.\nIf a section is present but empty or contains placeholders (TBD, TODO) — log as <strong>High</strong>.</p>\n<h4>No Implementation Code</h4>\n<p>The architecture plan must contain <strong>only</strong> CODEMANIFEST and <code>.usages/</code> file artifacts.\nIf implementation code blocks in any programming language are found — log as <strong>Critical</strong>.</p>\n<hr>\n<h3>Phase 3: Flat Model Reconstruction</h3>\n<p><strong>Goal:</strong> Construct a cross-cell type graph from all CODEMANIFESTs in the plan — disregarding cell boundaries to reveal the\nfull picture.</p>\n<p>From each CODEMANIFEST in the plan, extract:</p>\n<ul>\n<li>All declared types (Entity and Routine) with their signatures</li>\n<li>All inter-type connections: parameter acceptance, return types, mutations, embeddings</li>\n<li>All Import relationships (source of each referenced type)</li>\n</ul>\n<p>Construct a unified type graph:</p>\n<ul>\n<li><strong>Vertices</strong> — all types across all plan CODEMANIFESTs + all imported types from existing cells</li>\n<li><strong>Edges</strong> — inter-type interactions (parameters, returns, mutations, embeddings, calls via Imports)</li>\n</ul>\n<p>Render the graph to the user as an ASCII diagram.</p>\n<hr>\n<h3>Phase 4: Flat Model Cohesion</h3>\n<p>Validate the type graph (Phase 3) for integrity.</p>\n<h4>Step 1. Type Graph Completeness</h4>\n<ul>\n<li>Every type referenced in signatures (parameters, returns), mutations (<code>Object::Target</code>), or embeddings (\n<code>-&gt;Entity: {}</code>) must exist as a declared type in the model</li>\n<li>No implicit types — types that are used but nowhere declared (neither in plan CODEMANIFESTs nor in existing cells\nvia Imports)</li>\n</ul>\n<p>If a type is used but undeclared — log as <strong>Critical</strong> (model gap blocks implementation).</p>\n<h4>Step 2. Graph Connectivity</h4>\n<ul>\n<li>All types must be reachable from entry points (EntryPoint types — those that initiate data flows)</li>\n<li>No \"dangling\" types — types that nothing uses and that use nothing (entry points excepted)</li>\n<li>A type that no other type references and that is not itself an entry point is suspicious</li>\n</ul>\n<p>Unreachable types — log as <strong>High</strong> (possibly extraneous or missing a connection).\nDangling types — log as <strong>Medium</strong> (may serve future expansion, but should be explicitly documented).</p>\n<h4>Step 3. Connection Consistency</h4>\n<ul>\n<li>Where type A passes type X to type B — type X must have a consistent form (same source, same signature)</li>\n<li>Input/output types must align along interaction chains: output of type N must match input of type N+1</li>\n<li>No \"magical\" type transformations — every type transition must be explained by a contract (signature, mutation,\nembedding)</li>\n</ul>\n<p>Inconsistencies — log as <strong>Critical</strong>.</p>\n<hr>\n<h3>Phase 5: Cell Cohesion</h3>\n<p><strong>Goal:</strong> Verify that cell boundaries are well-defined — high internal cohesion, minimal cross-cell coupling.</p>\n<h4>Step 1. Internal Cell Cohesion</h4>\n<p>For each cell in the plan:</p>\n<ul>\n<li>Types within a single cell must interact with each other (exchange data via parameters, returns, mutations)</li>\n<li>A type in a cell with no interaction with any other type in that cell signals a potential composition error</li>\n</ul>\n<p>If a type has no connections to other types in its cell — log as <strong>Medium</strong> (may belong in a different cell).</p>\n<h4>Step 2. Boundary Soundness</h4>\n<ul>\n<li>Each cell must have a single area of responsibility — describable in one phrase without \"and\" (see <code>goga-cookbook</code>)</li>\n</ul>\n<p>If a cell requires \"and\" to describe — log as <strong>High</strong> (consider splitting).\nIf closely coupled types are placed in separate cells without justification — log as <strong>Medium</strong>.</p>\n<h4>Step 3. Dependency Directionality</h4>\n<ul>\n<li>Dependencies must flow from leaves to root: cells without Imports are designed first, dependent cells follow</li>\n<li>No cycles between cells: if cell A imports from cell B, cell B must not import from cell A</li>\n<li>Implementation order in the plan must match the dependency direction</li>\n</ul>\n<p>Cycles — log as <strong>Critical</strong>.\nImplementation order mismatch — log as <strong>Critical</strong> (implementation will be blocked).</p>\n<h4>Step 4. Minimal Cross-Cell Coupling</h4>\n<ul>\n<li>A cell must not import more types from another cell than necessary</li>\n<li>If cell A imports a significant portion of cell B's types — this indicates incorrect decomposition (cell B is too\ngranular or boundaries are misdrawn)</li>\n</ul>\n<p>If a cell imports the majority of another cell's types — log as <strong>High</strong> (re-examine boundaries).</p>\n<h4>Step 5. Usages Connections Between Cells</h4>\n<p>Use <code>goga-cookbook</code> as the authoritative source for usages validation rules.\nVerify that <code>.usages/</code> files and their CODEMANIFEST connections conform to <code>goga-cookbook</code> principles.</p>\n<p>Violations — log as <strong>High</strong>.</p>\n<h4>Step 6. Usages Isolation</h4>\n<p><strong>Principle:</strong> Every <code>.usages/</code> file must be self-contained — consumers must understand the pattern without consulting\nother practices. Cross-references to other practices create implicit dependencies and violate isolation\n(see <code>goga-cookbook</code>).</p>\n<p>For each <code>.usages/</code> file in the plan, verify:</p>\n<ul>\n<li>The file contains no references to other practices — no names of other usage files, no backticks referencing\npractices from other <code>.usages/</code></li>\n<li>All necessary context is self-contained — consumers must not need to locate additional practices</li>\n</ul>\n<p>Cross-reference to another practice — log as <strong>High</strong> (isolation violation).\nNon-self-contained usage file — log as <strong>High</strong>.</p>\n<hr>\n<h3>Phase 6: CODEMANIFEST Requirements Sufficiency</h3>\n<p><strong>Goal:</strong> Verify that CODEMANIFESTs contain sufficient information to support implementation.</p>\n<h4>Step 1. Contract Precision</h4>\n<ul>\n<li>Signatures must be unambiguous — a method/property signature must clearly convey its behavior, input types, and return\ntypes</li>\n<li>No methods/properties open to dual interpretation</li>\n<li>Mutations and embeddings must be justified (not used simply \"because available\") — see criteria in <code>goga-cookbook</code></li>\n<li>Entity vs Routine classification must be justified for each type — see criteria in <code>goga-cookbook</code></li>\n<li>Type, method, and property names must conform to target language conventions (from <code>goga-lang-disp</code>)</li>\n</ul>\n<p>Ambiguous signature — log as <strong>High</strong>.\nUnjustified mutation/embedding — log as <strong>Medium</strong>.\nIncorrect Entity/Routine classification — log as <strong>High</strong>.\nNon-conformant naming — log as <strong>High</strong>.</p>\n<h4>Step 2. Usages Quality</h4>\n<p>For each CODEMANIFEST of the plan:</p>\n<ul>\n<li>The header <code>Usages:</code> directive must include the project's base usages retrieved via <code>goga-codemanifest-base</code>\n(<code>goga config codemanifest.usages</code>) — these practices are mandatory for every CODEMANIFEST in the project</li>\n</ul>\n<p>Missing base usage in <code>Usages:</code> — log as <strong>High</strong>.</p>\n<h4>Step 3. Annotation Quality</h4>\n<p>For each annotation in every CODEMANIFEST of the plan:</p>\n<ul>\n<li>The global <code>Annotations:</code> directive (document header) must contain the project's base annotations retrieved via skill <code>goga-codemanifest-base</code>, transferred <strong>as-is (verbatim)</strong> — without rephrasing, summarizing, or modifying the original text</li>\n<li>Annotations must not contain technical implementation details</li>\n<li>Annotations must contain sufficient information for implementation — implementers must not need to guess behavior</li>\n<li>For non-trivial logic, describe an algorithm or execution flow (step-by-step) where achievable</li>\n<li>Document constraints and edge cases: empty input, None/null, errors, boundary values</li>\n<li>No placeholders (TBD, TODO) — annotations must be complete</li>\n</ul>\n<p>Missing base annotation in global <code>Annotations:</code> — log as <strong>High</strong>.\nBase annotation rephrased or modified (not transferred as-is) — log as <strong>High</strong>.\nInsufficient annotation — log as <strong>Critical</strong>.\nNon-conformant annotation format — log as <strong>High</strong>.\nMissing step-by-step logic description — log as <strong>High</strong>.\nMissing edge cases — log as <strong>Medium</strong>.</p>\n<h4>Step 4. Task Requirements Coverage</h4>\n<p>If the task file <code>docs/tasks/&lt;topic&gt;.md</code> exists:</p>\n<ul>\n<li>Each requirement from the \"Description\" section must map to type(s) in the plan that fulfill it</li>\n<li>Each acceptance criterion must have a contractual basis in the plan — the plan must enable fulfilling the criterion</li>\n<li>Each risk from the task must be accounted for (via types, annotations, or architectural decisions)</li>\n<li>Each subtask from the \"Scope\" section must be covered by the plan (if the task is decomposed)</li>\n</ul>\n<p>Uncovered requirement — log as <strong>Critical</strong>.\nUnfulfilled acceptance criterion — log as <strong>High</strong>.\nUnaccounted risk — log as <strong>Medium</strong>.</p>\n<hr>\n<h3>Phase 7: Impact on Existing Architecture</h3>\n<p>For cells marked as modifiable (already present in the project schema):</p>\n<h4>Step 1. Modification Correctness</h4>\n<ul>\n<li>The plan must explicitly distinguish modified cells from newly created ones</li>\n<li>For modified cells, the plan must provide a diff: additions, changes, and deletions</li>\n<li>Modifications must not break existing contracts referenced by other cells</li>\n</ul>\n<p>Modification not described as a diff — log as <strong>High</strong>.\nModification breaks existing contracts — log as <strong>Critical</strong>.</p>\n<h4>Step 2. Impact on Dependent Cells</h4>\n<ul>\n<li>Determine whether changes affect cells not mentioned in the plan but dependent on modified cells</li>\n<li>Run <code>--depends-on &lt;cell_path&gt;</code> to locate dependent cells</li>\n</ul>\n<p>Unacknowledged affected cells — log as <strong>High</strong>.</p>\n<hr>\n<h3>Phase 8: Report and Finding Resolution (Interactive)</h3>\n<p>Aggregate all findings from Phases 2–7 before presenting. Sort by severity: Critical → High → Medium.</p>\n<p>Present findings <strong>one at a time</strong>. For each finding:</p>\n<h4>Step 1. Present the Finding</h4>\n<p>Display one finding with:</p>\n<ul>\n<li><strong>Severity</strong> (Critical / High / Medium)</li>\n<li><strong>Direction</strong> (Flat Model / Cells / Requirements / Existing Architecture)</li>\n<li><strong>Location</strong> — precise reference to the type, cell, plan section, or CODEMANIFEST</li>\n<li><strong>Issue</strong> — clear problem description</li>\n<li><strong>Suggested fix</strong> — specific change required, not vague guidance</li>\n</ul>\n<h4>Step 2. Request User Decision</h4>\n<p>Use AskUserQuestion with these options:</p>\n<ol>\n<li><strong>Apply suggested fix</strong> — apply the fix to the architecture plan immediately</li>\n<li><strong>Propose alternative</strong> — user provides a different fix approach</li>\n<li><strong>Skip</strong> — user defers the finding</li>\n</ol>\n<h4>Step 3. Apply Decision</h4>\n<ul>\n<li><strong>Apply suggested fix</strong>: update the architecture plan, then re-verify that the fix introduces no\nnew issues (re-run relevant checks). Report the re-verification result briefly.</li>\n<li><strong>Skip</strong>: mark the finding as \"skipped\" and proceed.</li>\n<li><strong>Propose alternative</strong>: discuss the alternative with the user, agree on a fix, apply it,\nre-verify.</li>\n</ul>\n<h4>Step 4. Proceed to Next Finding</h4>\n<p>Repeat from Step 1 for the next finding. Display a brief counter: \"Finding 3 of 12\".</p>\n<p>After all findings are processed, present the summary:</p>\n<ul>\n<li><strong>Fixed</strong>: N findings (grouped by severity and direction)</li>\n<li><strong>Skipped</strong>: N findings (grouped by severity and direction)</li>\n<li><strong>Architecture plan status</strong>: updated / unchanged</li>\n</ul>\n<hr>\n<h2>Output</h2>\n<ul>\n<li>Finding summary: fixed/skipped counts by severity and direction</li>\n<li>Updated architecture plan file (if fixes were applied)</li>\n<li>Verification verdict: passed / failed</li>\n</ul>\n<hr>\n<h2>Final Self-Check</h2>\n<p>Before completion, verify:</p>\n<ol>\n<li>Was the DSL specification loaded via <code>goga-cell</code> and <code>goga-cookbook</code>?</li>\n<li>Was the current project schema loaded?</li>\n<li>Was plan structure validated (all 4 mandatory sections, no implementation code)?</li>\n<li>Was the flat model reconstructed (unified type graph)?</li>\n<li>Was flat model cohesion validated (completeness, reachability, consistency)?</li>\n<li>Was cell cohesion validated (internal cohesion, boundaries, directionality, minimal coupling, usages connections)?</li>\n<li>Was usages isolation validated (no cross-references to other practices, self-contained files)?</li>\n<li>Was requirements sufficiency validated (contract precision, usages quality, annotation quality)?</li>\n<li>If a task file exists — was task requirements coverage verified?</li>\n<li>Was consistency with existing architecture validated (modifications, dependent cells)?</li>\n<li>Was each finding presented individually with a fix decision?</li>\n<li>Were approved fixes applied and re-verified?</li>\n<li>Was a fixed/skipped findings summary provided?</li>\n<li>Were language rules loaded and applied via <code>goga-lang-disp</code>?</li>\n</ol>\n<p>If any answer is \"no\" — complete the missing verification before returning.</p>\n<hr>\n","files":[{"path":"SKILL.md","sizeBytes":15068,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-10T18:19:05.131825Z","sha256":"92C3BE650CDF1B10086BB0DF0B707314D13A8E348B1925EAA3E79FDFEE9B5DA4","sizeBytes":5426},"review":null,"source":{"repositoryUrl":"https://github.com/qarium/goga","path":"goga/assets/skills/goga-review-arch","license":"BSD-3-Clause","commit":"9fdb39b191bec889e345e42ffa1549d2727ca247","subtreeSha":"1045A3B586F87CB156034F531B2419FE050C02F4F2E8B3490C9769293AD7ACE4","lastSyncedAt":"2026-09-20T13:50:46.125615Z"},"reviewedAt":"2026-09-10T18:19:51.402538Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/qarium/goga/tree/1.2.x/goga/assets/skills/goga-review-arch"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install qarium-goga@llmmart"},{"target":"git","command":"git clone https://github.com/qarium/goga.git"}]}