# Goga Review Plan

> Verify execution plan completeness and correctness

- Skill: `qarium/goga-review-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add qarium/goga-review-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qarium/goga-review-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: qarium (https://skillmd.com/u/qarium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qarium/goga-review-plan

---

# Plan Verification

## Objective

Verify the execution plan (the file at the path printed by `goga history path -f plan.md`) for **completeness and correctness** against the design document and `CODEMANIFEST` contracts before passing to ralphex.

You **verify** the plan, **report** findings, and **fix** the plan upon discovery of issues (subject to user approval).

---

## Key Principle

**Every affected contract obligation and design decision must be traceable within the plan.** The plan covers only entities affected by the current feature (as defined in the design document). For all entities the plan claims to cover, it must be correct with respect to the contract and complete with respect to the design. Tasks in the plan that are not traceable to any contract or design also constitute a finding.

## Verifiable Artifact

- Plan file at the path printed by `goga history path -f plan.md` — the execution plan, verified against sources of truth

---

## Phases

### Phase 1: Load Context

1. Invoke `goga-lang-disp` via the **Skill tool** — retrieve the target language skill.
   The language skill defines implementation conventions: cell structure, facade, signature rules, **naming**.
   Examples in other skills may use naming conventions of one language (e.g., snake_case), while the target language
   requires different conventions (e.g., PascalCase) — the language skill is the authoritative source for the target language.
2. Read the plan from the path printed by `goga history path -f plan.md`
3. Read the design document from the path printed by `goga history path -f design.md`
4. Read all relevant `CODEMANIFEST` files referenced by the design document
5. Load the DSL specification and DSL application principles:
   - Invoke `goga-cell` via the **Skill tool** — obtain the DSL reference
     (signature syntax, rules for Imports, Usages, Annotations, types, mutations, embeddings, constraints)
   - Invoke `goga-cookbook` via the **Skill tool** — understand cell and CODEMANIFEST design principles
     (when to use Entity vs Routine, when to apply mutations and embeddings, usage file authoring guidelines, cell granularity)

---

### Phase 2: Run Linter

Execute:
```
goga lint
```

If the linter reports errors, record each error as a **Critical** finding. CODEMANIFEST syntax must be valid before the plan can pass verification.

---

### Phase 3: Consistency — Plan vs CODEMANIFEST

The plan covers only entities affected by the current feature (as defined in the design document), not the entire CODEMANIFEST. Use CODEMANIFEST as a correctness reference, not a completeness checklist.

For each entity/obligation the plan **actually** covers:

#### Step 1. Entity Details

For each contract entity referenced in the plan:
- Verify the entity name and facade obligation match CODEMANIFEST — record as **Critical** on mismatch
- Verify the plan specifies implementation in the correct file `location` per CODEMANIFEST — record as **Critical** on error
- Verify method/property **descriptions** from the contract are reflected in task instructions — record as **High** if absent

#### Step 2. Annotation Detailing

For each `annotations` declaration within the plan's scope (at file, entity, or method/property level):
- Verify the plan embeds annotation content into the corresponding task descriptions
- Verify cascading: file-level annotations appear in every task of the package, entity-level in entity tasks, method-level in the method task
- If annotations are absent from tasks — record as **High**

#### Step 3. Import Context

For each `Imports` entry within the plan's scope:
- Verify plan tasks reference imported types using correct names (including `AS` aliases)
- For imported usages from `Imports` → `Usages`: verify plan tasks correctly reference the imported usage content, including the source path `{from_path}/.usages/{usage_name}.md`
- If import context is absent from tasks that use imported types — record as **High**
- If imported usage context is absent from tasks that depend on the imported practice — record as **High**

#### Step 4. Re-export Coverage

For each re-export block the plan claims to handle:
- Identify a task that ensures the name is importable from the facade
- If a re-export referenced in the plan is not covered — record as **Critical**

#### Step 5. Mutation Coverage

For each `Type::` mutation the plan claims to handle:
- Identify a task that implements the mutation
- If a mutation referenced in the plan is not covered — record as **High**

---

### Phase 4: Consistency — Plan vs Design Document

#### Step 1. Design Entity Traceability

For each entity and design decision described in the design document:
- Identify where they are reflected in the plan's tasks
- If a design decision is absent from all tasks — record as **High**

#### Step 2. Test Scenario Traceability

For each test scenario in the design document:
- Identify the corresponding test instruction in the plan's tasks
- If a test scenario is absent — record as **Medium**

#### Step 3. Absence of Orphan Tasks

For each task in the plan:
- Verify it is traceable to a contract entity, design decision, or justified infrastructure requirement
- If a task has no traceable origin — record as **Medium**

---

### Phase 5: TDD Completeness

For each **coding task** in the plan (entity skeleton, property, method, mutation implementation):

Verify the task includes all TDD steps as checkboxes:
1. **Contract tests** — written first, expected to fail
2. **Code** — implementation steps
3. **Interface verification** — run contract tests
4. **Logical tests** — behavioral tests
5. **Debugging** — run tests, fix the implementation (NOT the tests)
6. **Contract re-verification** — verify contract obligations
7. **Lint** — formatting check

If any TDD step is absent — record as **High**.

Infrastructure tasks (Cell structure, facade, re-exports) are exempt — they follow a simplified workflow.

---

### Phase 6: Self-contained Tasks

For each task in the plan, verify all of the following. If any check fails — record as **High**:

1. Does the task contain its own context paragraph explaining what it does and which contract entities it covers? If absent — record as **High**.
2. Does the task include relevant imports, Usages, and annotations? If absent — record as **High**.
3. Does the task specify target files? If absent — record as **High**.
4. Does the task depend on another task for implementation context (e.g., "see Task 3 for API") instead of inlining it? If so — record as **High**.

---

### Phase 7: Task Order

Verify the overall task order conforms to the convention:

1. **Infrastructure tasks** (Cell structure, facade, re-exports)
2. **Entity skeleton tasks**
3. **Property implementation tasks**
4. **Method implementation tasks**
5. **Interface mutation tasks**
6. **Integration test tasks**

In a multi-package plan:
- Leaf packages are processed before parent packages
- Each package's coding tasks complete before the next package begins

If the order is violated — record as **Medium**.

---

### Phase 8: Usages Coverage

For each `Usages` entry within the plan's scope (from affected entities per the design document):
- Identify at least one task in the plan that references this Usages entry
- Verify the task contains specific information (what to use, how to invoke), not merely a name reference
- If the Usages entry value is a file path — verify the plan reflects the actual file content, not merely the path or usage name

For each imported usage from `Imports` → `Usages` within the plan's scope:
- Identify at least one task referencing this imported usage
- Verify the task references the correct source path `{from_path}/.usages/{usage_name}.md`
- Verify the task contains specific information from the imported usage, not merely a name reference

For each planned local `.usages/` file specified in the design document:
- Identify a task or step that creates or extends the `.usages/<category-name>.md` file
- Verify the task specifies the expected file content
- If the file extends an existing category — verify the plan specifies addition, not replacement
- Verify file creation is planned alongside the code, not as a separate stage

If a Usages entry is absent from all tasks — record as **Medium**.
If a Usages mention is too vague — record as **Low**.
If a Usages file path is referenced but its content is not reflected — record as **Medium**.
If an imported usage is absent from all tasks — record as **Medium**.
If a planned local `.usages/` file lacks a creation task — record as **Medium**.

---

### Phase 9: CODEMANIFEST Read-Only Check

For each task in the plan:
- Verify no task instructs the implementation agent to modify `CODEMANIFEST` files
- Verify the plan instructs the implementation agent not to modify CODEMANIFEST files (look for a "read-only" warning in the task context)

If a task proposes CODEMANIFEST modification — record as **Critical**.
If the "read-only" warning is absent — record as **Medium**.

---

### Phase 10: Report and Fix Findings (Interactive)

Aggregate all findings from Phases 2–9 before presenting them. Sort by severity: Critical → High → Medium → Low.

Present findings **one at a time**. For each finding:

#### Step 1. Present the Finding

Display one finding with:

- **Severity** (Critical / High / Medium / Low)
- **Direction** (CODEMANIFEST / Design / TDD / Self-containment / Order / Usages / Read-Only)
- **Location** — exact reference to the task, plan section, or CODEMANIFEST line
- **What's wrong** — clear description of the problem
- **Suggested fix** — the precise change required, not vague advice

#### Step 2. Request User Decision

Use AskUserQuestion with options:

1. **Apply suggested fix** — apply the fix to the plan immediately
2. **Suggest alternative** — the user describes a different fix approach
3. **Skip** — the user dismisses the finding

#### Step 3. Apply the Decision

- **Apply suggested fix**: update the plan file at the path printed by `goga history path -f plan.md`, then re-verify that the fix introduces no new issues (re-run the relevant checks). Briefly report the re-verification result.
- **Skip**: record the finding as "skipped" and proceed.
- **Suggest alternative**: discuss the alternative with the user, agree on a fix, apply it, and re-verify.

#### Step 4. Proceed to Next Finding

Repeat from Step 1 for the next finding. Display a brief counter: "Finding 3 of 12".

After processing all findings, display the summary:

- **Fixed**: N findings (listed by severity and direction)
- **Skipped**: N findings (listed by severity and direction)
- **Plan status**: updated / unchanged

---

## Output

- Findings summary: count of fixed / skipped findings by severity and direction
- Updated plan file (if fixes were applied)
- Verification verdict: passed / failed

---

## Final Self-Check

Before completing, verify:

1. Were all relevant CODEMANIFEST files read and each plan entity verified for correctness against the contract (names, locations, descriptions, annotations, imports)?
2. Was the design document read and each entity/design decision/test scenario traced in the plan? Were orphan tasks identified?
3. Was `goga lint` executed and results analyzed?
4. Was each coding task checked for TDD completeness (all 7 steps)?
5. Was each task checked for self-contained context?
6. Was task order verified against the convention?
7. Was each Usages entry checked for coverage in the plan?
8. Was each imported usage from `Imports` → `Usages` checked for coverage and correct source path reference?
9. Was each planned local `.usages/` file checked for a creation task with expected content?
10. Was each task checked for CODEMANIFEST "read-only" compliance?
11. Was each finding presented one at a time with a fix decision via AskUserQuestion?
12. Were approved fixes applied and re-verified?
13. Was a summary of fixed/skipped findings provided?

If any answer is "no" — complete the missing verification before returning.

---