Skip to content

GZKit Go-Live Gap Analysis

What Must Be True Before Students Can Use GZKit Independently

Date: 2026-03-08 Litmus test: RHEA (first greenfield project governed by gzkit) Target: CIDM 6330/6395 graduate students

Definition of "Go-Live"

A student can:

  1. Install gzkit in under 5 minutes
  2. Bootstrap a new project (gz init) without instructor help
  3. Write a PRD and first ADR using templates and guides
  4. Create task briefs from their ADR checklist
  5. Implement, run gates, and attest — with clear error messages when something goes wrong
  6. Present their governed project to an instructor who can verify the governance trail

The instructor should not need to explain gzkit to the student. The documentation and error messages must do that work.

Current State (v0.8.0)

Capability Status Notes
Installation Ready uv tool install gzkit works cleanly
gz init Ready Creates correct structure
gz prd Ready Generates template, writes ledger
gz plan Ready Generates ADR with checklist scaffolding
gz specify Ready Creates OBPI briefs from checklist items
gz gates Ready Runs gate checks, records to ledger
gz closeout Ready Presents verification steps
gz attest Ready Records attestation with prereq checks
gz status Ready Shows lifecycle state from ledger
Documentation Partially ready Comprehensive but assumes governance fluency
Error messages Partially ready Functional but not always instructive
Student onboarding Not ready No first-project tutorial (now provided in docs/examples/)
Greenfield validation Not tested RHEA is the test — hasn't been run yet

Blockers (Must Fix Before Go-Live)

Blocker 1: RHEA Bootstrap Must Succeed

What: Run the full governance cycle on RHEA (gz init → gz prd → gz plan → gz specify → implement → gz gates → gz attest) and document every friction point.

Why it blocks: If gzkit can't govern a simple greenfield library project, it can't govern a student project. RHEA is the proof.

Definition of done:

  • [ ] gz init creates correct structure in RHEA
  • [ ] gz prd generates valid PRD from RHEA's vision
  • [ ] gz plan creates ADR with parseable checklist
  • [ ] gz specify correctly links OBPI briefs to checklist items
  • [ ] gz gates finds and runs tests in RHEA's structure
  • [ ] gz attest records attestation without errors
  • [ ] Friction points documented as GitHub issues

Effort estimate: 1 focused session (2-4 hours)

Blocker 2: Student-Facing Documentation Must Exist

What: The docs/examples/ directory (created in this session) must be linked from gzkit's main documentation and discoverable by students.

Why it blocks: Students won't find docs/examples/ unless it's linked from the quickstart or main docs index.

Definition of done:

  • [ ] docs/user/quickstart.md links to tutorial-first-project.md
  • [ ] docs/user/index.md or README links to docs/examples/
  • [ ] Glossary is linked from concept docs
  • [ ] Cross-links between guides are all valid

Effort estimate: 30 minutes

Blocker 3: pyproject.toml / Project Scaffolding

What: gz init should detect or prompt for Python project structure and optionally create pyproject.toml if missing.

Why it blocks: Students starting from mkdir my-project && cd my-project won't have a pyproject.toml. GZKit's gate commands (gz gates) run uv run -m unittest discover tests, which requires a valid Python project with uv dependency resolution. If there's no pyproject.toml, this fails with a confusing error.

Definition of done:

  • [ ] gz init warns if no pyproject.toml found
  • [ ] Error message explains: "Run uv init first to create a Python project"
  • [ ] OR: gz init offers to run uv init for the user
  • [ ] Documentation mentions uv init as a prerequisite

Effort estimate: 1-2 hours (depending on approach)

Gaps (Should Fix Before Go-Live)

Gap 1: Simplified Brief Generation

What: The OBPI template has 12+ sections. Students need a 5-section version (objective, scope, requirements, acceptance criteria, verification).

Current workaround: Students can use the simplified task template from docs/examples/templates/task-template.md manually, but gz specify still generates the full template.

Options:

Option Effort Impact
A: Add --simple flag to gz specify Medium (2-4 hrs) Clean UX; students get right template
B: Add mode: student to .gzkit.json Medium (2-4 hrs) All commands adjust automatically
C: Document "ignore sections you don't need" Low (done) Works but feels messy

Recommendation: Option B — a mode: student in config that generates lighter templates across all commands. This would also suppress the decomposition scorecard and reduce the ADR template.

Gap 2: Glossary Integration

What: The glossary (now in docs/examples/glossary.md) should be part of gzkit's published documentation, not just the examples directory.

Action: Move or copy to docs/user/glossary.md and add to mkdocs nav.

Effort: 15 minutes

Gap 3: Error Message Improvement

What: When a gate fails, the error should explain what to do, not just what failed.

Current:

Text Only
Gate 2 FAILED
  Command: uv run -m unittest discover tests
  Return code: 1

Better:

Text Only
Gate 2 (TDD) FAILED

  Command: uv run -m unittest discover tests
  Return code: 1

  What this means: Your tests did not pass. Gate 2 requires all unit
  tests to pass before attestation.

  Next steps:
    1. Run the command above manually to see which tests failed
    2. Fix the failing tests
    3. Run `gz gates --adr ADR-0.1.0 --gate 2` again

Effort: 2-4 hours (update gate output formatting in cli.py)

Gap 4: Example ADR in a Non-GZKit Domain

What: All 9 existing ADRs are about gzkit itself. Students need to see an ADR for a "normal" project. The first-project tutorial provides one (reading list), but a second example in a different domain would help.

Action: Complete the RHEA bootstrap — it naturally produces a non-GZKit ADR for a library project.

Effort: Covered by Blocker 1

Gap 5: Instructor Verification Guide

What: How does an instructor verify that a student actually used gzkit governance? What should they look at?

Needed:

  • A 1-page "instructor checklist" showing what to inspect
  • How to read .gzkit/ledger.jsonl to verify governance events
  • How to check that attestation is recorded
  • How to distinguish real governance from retroactive ceremony

Effort: 1-2 hours to write

Nice-to-Haves (Post Go-Live)

Feature Value Effort
gz init --template student One-command setup with student mode, simplified templates, pyproject.toml High (8+ hrs)
gz explain <concept> CLI command that prints glossary definitions inline Medium (4 hrs)
Learning-mode verbose output Commands print "why" explanations alongside "what" High (8+ hrs)
Student project gallery Curated examples of governed student projects Ongoing
Curriculum mapping guide How to map gzkit ceremonies to sprint milestones Medium (4 hrs)
Video walkthrough Screen recording of the first-project tutorial Medium (2-3 hrs)

Go-Live Checklist

Must be complete

  • [ ] RHEA bootstrap succeeds end-to-end (Blocker 1)
  • [ ] Student docs linked from main gzkit docs (Blocker 2)
  • [ ] pyproject.toml prerequisite documented or handled (Blocker 3)

Should be complete

  • [ ] Simplified brief generation (Gap 1)
  • [ ] Glossary in published docs (Gap 2)
  • [ ] Improved gate error messages (Gap 3)
  • [ ] Instructor verification guide (Gap 5)

Nice to have

  • [ ] gz init --template student
  • [ ] gz explain <concept>
  • [ ] Video walkthrough
Text Only
Week 1:  Bootstrap RHEA (Blocker 1)
         ├── Run gz init → gz attest cycle
         ├── File friction points as GitHub issues
         └── Fix any CLI bugs discovered

Week 2:  Documentation integration (Blocker 2 + Gap 2)
         ├── Link docs/examples/ from quickstart
         ├── Move glossary to docs/user/
         └── Validate all cross-links

Week 2:  pyproject.toml handling (Blocker 3)
         └── Add warning or prompt to gz init

Week 3:  Student UX improvements (Gaps 1, 3, 5)
         ├── Simplified brief template (--simple or mode: student)
         ├── Better gate error messages
         └── Instructor verification guide

Week 4:  Dry run with 1-2 students
         ├── Observe where they get stuck
         ├── Fix discovered issues
         └── Declare go-live ready

Total estimated effort: 2-3 focused work sessions (8-12 hours) for the blockers, plus 1-2 sessions for the gaps.

The Litmus Test

RHEA answers the fundamental question:

Can a developer (or student) go from an empty directory to a governed, attested feature using only gzkit's CLI and documentation?

If yes → gzkit is ready for classroom use. If no → the specific failure points become the go-live backlog.

Everything in this document flows from that single question.