docs/project/assessments

ClearGrow Assessment Framework

Systematic firmware assessment framework using GitHub Issues for tracking.

Repository Structure

/opt/repos/
├── controller/    → bnich/ClearGrow-Controller (ESP32-S3)
├── probe/         → bnich/ClearGrow-Probe (nRF52840)
├── docs/          → bnich/ClearGrow-Documentation (issues live here)
└── simulator/     → (not yet a repository)

Important: Run git/gh commands from within each subdirectory.

Architecture

Issues live in the repo for their platform:

┌───────────────────────────────────────┐
│       bnich/ClearGrow-Controller      │
│  • Controller issues                  │
│  • ESP32-S3 code                      │
└───────────────────────────────────────┘

┌───────────────────────────────────────┐
│         bnich/ClearGrow-Probe         │
│  • Probe issues                       │
│  • nRF52840 code                      │
└───────────────────────────────────────┘

┌───────────────────────────────────────┐
│     bnich/ClearGrow-Documentation     │
│  • Product docs                       │
│  • Assessment framework               │
└───────────────────────────────────────┘

Quick Start

# 1. Setup labels (one time)
# Use prompt: prompts/00_SETUP.md

# 2. Start assessment session
# Use prompt: prompts/01_ASSESSMENT_SESSION.md

Session Design

Each prompt is run once in a fresh Claude Code session:

1. Copy prompt into new session
2. Claude executes the work
3. Subagents commit their changes
4. Orchestrator does final commit + push
5. Session ends with handoff summary for next session

Prompts

Prompt	Actor	Purpose
00_SETUP.md	Human/Claude	One-time label setup
01_ASSESSMENT_SESSION.md	Orchestrator	Query status, spawn subagents, push
02_ASSESSMENT_SUBAGENT.md	Subagent	Assess category, create issues
03_REMEDIATION_SESSION.md	Orchestrator	Query backlog, spawn subagents, push
04_REMEDIATION_SUBAGENT.md	Subagent	Fix gap, update issue
05_BUILD_FIX_SUBAGENT.md	Subagent	Build, fix errors
06_VERIFICATION_SESSION.md	Orchestrator	Query verify queue, spawn subagents, push
07_VERIFICATION_SUBAGENT.md	Subagent	Verify fix, close/reopen issue
08_LIBRARIAN.md	Subagent	Update product docs
09_CALIBRATE_PLANS.md	Standalone	Sync PLAN files with actual codebase

Actor Model

Actor	Role	Reads	Writes
Orchestrator	Scrum master	Issue metadata only	Final commit + push
Assessment Subagent	Find gaps	PLAN, code	Creates issues, commits
Remediation Subagent	Fix gaps	Full issue, code	Code, comments, commits
Build & Fix Subagent	Make it compile	Build output	Code, comments, commits
Verification Subagent	Confirm fix	Full issue, code	Close/reopen issue
Librarian	Update docs	Closed issue list	Docs, commits

Label Scheme

Labels are created in BOTH Controller and Probe repos.

Severity

• severity:critical - Non-functional, data loss, security
• severity:high - Major subsystem impaired
• severity:medium - Degraded performance
• severity:low - Code quality

Status

• status:backlog - Ready to work
• status:in-progress - Being fixed
• status:verify - Awaiting verification
• (closed) - Done

Category

• Controller: cat:boot-init, cat:task-arch, cat:memory-mgmt, etc.
• Probe: cat:boot-init, cat:thread-net, cat:power-mgmt, etc.

Common Commands

# List controller backlog
gh issue list --repo bnich/ClearGrow-Controller --label "status:backlog"

# List probe backlog
gh issue list --repo bnich/ClearGrow-Probe --label "status:backlog"

# View issue
gh issue view 12 --repo bnich/ClearGrow-Controller

# Update status
gh issue edit 12 --repo bnich/ClearGrow-Controller \
  --remove-label "status:backlog" --add-label "status:in-progress"

# Close issue
gh issue close 12 --repo bnich/ClearGrow-Controller

# Commit (from within subdirectory)
cd /opt/repos/controller
git add -A
git commit -m "fix: #12 add null check"

File Structure

cleargrow_framework/
├── README.md
├── MIGRATION_GUIDE.md
├── controller/
│   └── PLAN_Controller_Assessment.md     # 24 category checklists
├── probe/
│   └── PLAN_Probe_Assessment.md          # 12 category checklists
├── prompts/
│   ├── README.md
│   ├── 00_SETUP.md                       # One-time label setup
│   ├── 01-08_*.md                        # Session prompts
│   └── 09_CALIBRATE_PLANS.md             # Sync PLANs with codebase
└── legacy/                               # Flat-file version (deprecated)

What's in GitHub vs Files

In GitHub Issues	In Flat Files
Gaps (one per issue)	PLAN checklists
Progress updates	Prompts
Build results	Setup scripts
Status tracking

Migration

See MIGRATION_GUIDE.md if migrating from the legacy flat-file framework.