itpp-infrastructure/proposals/verdicttank/methodology.md

# VerdictTank Internal Proposal Methodology v1.0

**Status:** SETTLED  -  governing document for all VerdictTank/RFP Tank proposals  
**Effective:** 2026-08-11  
**Owner:** Sho'Nuff Brown (shogun of IT architecture)  
**Invocation:** `skill_view(name='verdicttank-proposal-pipeline', file_path='references/methodology.md')`

---

## 1. Pipeline Overview

The VerdictTank proposal pipeline converts a product brief into a deployed, reviewed, audited proposal page in one orchestrated run. It is NOT a general-purpose proposal tool  -  it is purpose-built for VerdictTank and RFP Tank, with specialized content teams, a mandatory blind audit, and multi-model conductor review.

```
Product Brief
    │
    ├─► Phase 1: Research (DeepSeek V4 Pro  -  current main model)
    │       Market sizing, competitor landscape, regulatory scan
    │       Output: research brief → /tmp/verdicttank-v4.0-research-brief.md
    │
    ├─► Phase 2: Content Creation (4 parallel teams)
    │       Marketing (Opus 4.8)     → HTML blocks: hero, value props, pricing, CTA
    │       Architecture (Opus 4.8)  → standalone architecture.html (dark theme, sections)
    │       Financial (Opus 4.8)     → bottom-up SOM/SAM/TAM, pricing model, unit economics
    │       Legal (Sonnet 5)         → ToS, Privacy, DPA, AI disclaimer, sub-processor audit
    │
    ├─► Phase 3: Assembly (DeepSeek V4 Pro  -  current main model)
    │       Merge 4 HTML blocks into index.html
    │       Reconcile SOM to Financial's authoritative number
    │       Insert legal blocks at designated markers
    │       Link architecture.html as standalone page
    │
    ├─► Phase 4: Internal Conductor Review (Sonnet 5 + Opus 4.8)
    │       Sonnet 5: brutal Shark Tank critic (what's wrong, what's missing, what's weak)
    │       Opus 4.8: sober validator + priority re-rank
    │       10-dimension scorecard: clarity, credibility, differentiation, TAM/SOM,
    │           GTM, tech feasibility, competitive moat, financial model, team, risk
    │       Output: critical-review.html (deployed alongside proposal)
    │
    ├─► Phase 5: Blind Audit (Opus 4.8  -  cold read, no prior context)
    │       7-item checklist executed against deployed page
    │       Every link checked, every number traced, every claim verified
    │       THIS IS MANDATORY. No proposal ships without a blind audit.
    │       v3.7 shipped with 4 verifiable errors because this step didn't exist.
    │
    ├─► Phase 6: External Conductor Review (fresh panel)
    │       Independent judges  -  no access to internal review results
    │       Majority-rules: Go / No-Go / Conditional Go
    │
    └─► Phase 7: Deploy + Outcome Tracking
            Deploy to proposals.itpropartner.com/verdicttank/
            Schedule T+90, T+180, T+365 outcome tracking checks
```

---

## 2. Tier Selection

Three cost tiers. Pick before dispatching teams. Tier determines which models run which roles.

| Tier | Cost | Target Score | Content Teams | Review | Blind Audit | Use Case |
|------|------|-------------|---------------|--------|-------------|----------|
| **Tier 1** | ~$0.80 | 6/10 | DeepSeek V4 Pro only | None | None | Internal draft, rapid iteration |
| **Tier 2** | ~$3.62 | 7-8/10 | Opus (narrative), Sonnet (architecture) | Internal only | Yes | Client-ready draft, first external showing |
| **Tier 3** | ~$6.69 | 9-10/10 | Opus (marketing, architecture, financial), Sonnet (legal) | Internal + External | Yes | Final proposal, investor deck, RFP response |

**Rule:** Tier 3 is the default for any proposal that leaves ITPP infrastructure. Tier 1 is for internal validation only. Tier 2 is for client drafts that will iterate.

**Actual v4.0 Tier 3 cost:** $6.69 (5 Opus dispatches + 1 Sonnet dispatch + assembly + 2 conductor reviews + blind audit). Budget cap: $10.00. Current spend: tracked against `hermes-agent-v5` LiteLLM key.

---

## 3. Team Composition & Model Rotation Protocol

### 3.1 Standard Team Assignments (Tier 3)

| Team | Model | Role | Output Format | Permission |
|------|-------|------|---------------|------------|
| Marketing & Narrative | Claude Opus 4.8 | Clean-sheet proposal narrative | HTML blocks with INSERT markers | Read-only |
| Technical Architecture | Claude Opus 4.8 | Industry-standard architecture document | standalone HTML (dark theme) | **Write to disk** (prevents truncation) |
| Financial Model | Claude Opus 4.8 | Bottom-up verified arithmetic | HTML blocks + verified numbers | Read-only |
| Legal & Governance | Claude Sonnet 5 | MVL framework, compliance tables | HTML blocks with INSERT markers | Read-only |

### 3.2 Model Rotation Protocol

**CRITICAL:** The delegation model must be set BEFORE each dispatch, then restored to `deepseek-v4-pro` immediately after. Failure to rotate burns budget on accidental Opus inference during assembly.

```
# Before dispatching Opus teams (marketing, architecture, financial):
hermes config set delegation.model claude-opus-4-8
delegate_task(...)  # dispatches marketing, architecture, financial as batch of 3
hermes config set delegation.model deepseek-v4-pro  # RESTORE IMMEDIATELY

# Before dispatching legal:
hermes config set delegation.model claude-sonnet-5
delegate_task(...)  # dispatches legal
hermes config set delegation.model deepseek-v4-pro  # RESTORE IMMEDIATELY

# Before conductor review (internal):
hermes config set delegation.model claude-sonnet-5  # for critic
delegate_task(...)
hermes config set delegation.model claude-opus-4-8  # for validator
delegate_task(...)
hermes config set delegation.model deepseek-v4-pro  # RESTORE

# Before blind audit:
hermes config set delegation.model claude-opus-4-8
delegate_task(...)
hermes config set delegation.model deepseek-v4-pro  # RESTORE
```

**Why DeepSeek V4 Pro is the default:** Budget protection. DeepSeek is orders of magnitude cheaper than Opus. The main model handles assembly, research, and coordination  -  all high-token, low-creativity work. Opus and Sonnet are reserved for tasks where their specific strengths justify the cost.

---

## 4. Content Team Brief Structure

Every team gets a self-contained brief file written to `/tmp/`. The brief must include:

1. **Context block:** What VerdictTank is, v3.7 review findings, the specific HTML blocks needed
2. **Rules block:** No em dashes, no fabrication, financial model is authoritative for SOM, honest about methodology gaps
3. **Output format block:** Exact HTML structure, INSERT markers, CSS variables to use
4. **Reference data:** SOM/TAM numbers, competitor names, pricing tiers, domain policy
5. **Pitfalls block:** Specific errors to avoid (from v3.7 postmortem)

### 4.1 Architecture Team  -  Special Handling

Architecture output is **written to disk**, not returned in the delegation summary. Reason: delegation summaries truncate at ~2K chars. Architecture documents are 50-100K chars. The team gets `write_file` permission targeting `/root/projects/itpp-infrastructure/proposals/verdicttank/architecture-v4.0-source.html`.

### 4.2 Legal Team  -  Special Requirements

Legal teams operate under the **Honest Methodology Gaps** rule:
- TESS (USPTO trademark database) is JavaScript-only  -  cannot be queried programmatically
- Open-web common-law search IS performed (SearXNG, Brave, Exa)
- Every legal output MUST disclose: "Formal TESS search not performed. Recommend trademark attorney clearance before Series A."
- Never fabricate TESS results. The gap is documented, not hidden.

---

## 5. SOM Reconciliation Rule

**The Financial model is the single source of truth for SOM.**

This rule exists because v4.0's Marketing team produced SOM of $7.91M while Financial produced $1.21M  -  a 6.5x gap. Both teams used the same TAM data. Financial's arithmetic was verified line-by-line. Marketing's was aspirational.

**Reconciliation protocol during assembly:**
1. Assembly agent loads both outputs
2. Identifies SOM mismatch
3. Forces Financial's number into the marketing blocks
4. Documents the override in the assembly notes
5. Blind auditor verifies the reconciliation

**Why not average or negotiate?** Because Financial's number was produced by a model that was explicitly instructed to verify every line of arithmetic. Marketing's model was instructed to sell. For revenue numbers, trust the accountant, not the salesperson.

---

## 6. Assembly Protocol

Assembly is performed by the main model (DeepSeek V4 Pro) and merges four independently produced HTML blocks into one coherent page.

### 6.1 Assembly Rules

1. **Single-source rule:** One `index.html`. Architecture is a separate `architecture.html` linked from the main page.
2. **SOM override:** Marketing's SOM → Financial's SOM. Document the override.
3. **INSERT marker resolution:** Legal and Marketing blocks use `<!-- INSERT: section_name -->` markers. Assembly replaces these with the actual content blocks.
4. **Consistency checks:**
   - All prices match Financial model
   - All feature claims trace to Architecture document
   - All legal disclaimers present
   - No forbidden model names in final output
   - Zero em dashes, zero double hyphens
   - Domain references: `verdicttank.com` (primary), `rfptank.com` (legacy/defensive only)
5. **CSS consistency:** All blocks use the same dark theme CSS variables (`--bg`, `--panel`, `--ink`, `--accent`, `--line`, etc.) defined in the architecture document.
6. **Footer consistency:** All pages share the same footer with origin, deployment date, and domain policy.

### 6.2 Deployment Map

| File | Deploy To | URL |
|------|-----------|-----|
| `index.html` | `app3:/home/ippadmin/htdocs/proposals.itpropartner.com/verdicttank/` | `https://proposals.itpropartner.com/verdicttank/` |
| `architecture.html` | Same directory | `https://proposals.itpropartner.com/verdicttank/architecture.html` |
| `critical-review.html` | Same directory | `https://proposals.itpropartner.com/verdicttank/review.html` |

**Origin:** `152.53.241.111` (app3, netcup RS 4000)  
**Served via:** nginx static file server, LE auto-certs

---

## 7. Blind Audit Protocol

**MANDATORY. No exceptions. No proposal ships without passing blind audit.**

### 7.1 Why This Exists

v3.7 shipped with four verifiable errors that a cold read would have caught:
1. Pricing table didn't match Financial model
2. Feature list referenced a deprecated API endpoint
3. Compliance section omitted GDPR data residency
4. CTA link pointed to staging, not production

The assembly agent was too close to the content to see these. The blind auditor reads the deployed page with zero prior context  -  exactly as a prospect would.

### 7.2 Audit Checklist

| # | Check | Method |
|---|-------|--------|
| 1 | Every link resolves (no 404s, no staging URLs) | Click every `href`, every CTA |
| 2 | Every number traces to Financial model | Cross-reference pricing table vs financial output |
| 3 | Every feature claim has architecture evidence | Cross-reference features vs architecture sections |
| 4 | Legal disclaimers present and complete | Verify ToS, Privacy, DPA, AI disclaimer blocks exist |
| 5 | Contact/CTA information correct | Verify email, phone, demo link |
| 6 | No placeholder text, no TODO markers, no lorem ipsum | Full page scan |
| 7 | CSS renders correctly on desktop and mobile viewports | Browser screenshot at 1280px and 375px |

### 7.3 Auditor Rules

- **Model:** Claude Opus 4.8 (strongest available for cold-read QA)
- **Context:** ZERO. The auditor gets ONLY the URL. No brief, no prior knowledge, no team outputs.
- **Output:** Pass/Fail with specific, numbered findings. Fail = blocks deployment until all items fixed.
- **Re-audit:** After fixes, a fresh auditor (different model or clean context) re-runs the checklist.

---

## 8. Conductor Review Integration

The pipeline uses TWO conductor reviews, not one.

### 8.1 Internal Conductor Review (Pre-Blind-Audit)

- **Critic:** Claude Sonnet 5  -  brutal, Shark Tank style. "What's wrong, what's missing, what's weak?"
- **Validator:** Claude Opus 4.8  -  sober, structured. Priority re-rank, FIX/DEFER/DEFEND treatment.
- **Scorecard:** 10 dimensions, 1-10 scale, weighted average.
- **Output:** `critical-review.html`  -  deployed publicly as a signal of confidence.

### 8.2 External Conductor Review (Post-Blind-Audit)

- **Fresh panel:** Judges have no access to internal review results or team outputs.
- **Majority-rules verdict:** Go (deploy), No-Go (block), Conditional Go (fix specified items).
- **Minimum passing score:** 7/10 for Tier 2, 8/10 for Tier 3.

### 8.3 Integration with shark-tank-review Skill

The `shark-tank-review` skill is the broader framework. This pipeline uses it as the review engine but adds:
- VerdictTank-specific 10-dimension weighting (financial model accuracy weighted 2x)
- Blind audit as a mandatory post-review gate
- Public deployment of the review as a confidence signal

When invoking: load `shark-tank-review` for the review phases, then execute blind audit as a separate step.

---

## 9. Legal & Trademark Guardrails

### 9.1 Trademark Clearance Methodology

1. **Open-web common-law search** (SearXNG, Brave, Exa)  -  search for "VerdictTank" + "software" + "AI" + "legal", check USPTO common-law marks, state registrations, domain ownership
2. **TESS search**  -  NOT performable programmatically (JavaScript-only USPTO database). This is a documented methodology gap.
3. **Recommendation:** Formal trademark attorney search before Series A funding. The open-web search found no conflicts, but TESS is the authoritative source for federal registrations.

### 9.2 Privacy & Compliance

- **MVL framework:** Terms of Service, Privacy Policy, Data Processing Agreement, AI Disclaimer, Limitation of Liability ($100 / 12 months fees), Jurisdiction (DE/GA)
- **Regulatory alignment:** GDPR, CCPA, NIST CSF 2.0
- **Sub-processor audit:** OpenAI (compliant), Anthropic (compliant), Google (compliant), DeepSeek (non-compliant  -  flagged with fallback described)
- **Corpus confidentiality:** 5-step anonymization pipeline, URL-to-Review and Chat-to-Refine raw content excluded from corpus

### 9.3 Honest Methodology Gaps

Any limitation in our research methodology must be DISCLOSED, not papered over:

| Gap | Disclosure |
|-----|-----------|
| TESS not searchable programmatically | "Formal TESS search not performed. Open-web common-law search completed." |
| DeepSeek sub-processor non-compliance | Flagged explicitly with fallback to compliant alternatives |
| Category existence risk (no standalone proposal review SaaS) | Acknowledged as market creation play, not hidden |

---

## 10. Outcome Tracking

Proposals are bets. Track whether the bets paid off.

### 10.1 Tracking Schedule

| Checkpoint | What to Measure | Method |
|------------|----------------|--------|
| T+90 | Page views, inbound inquiries, demo requests | Analytics + CRM |
| T+180 | Pipeline generated from proposal, conversion rate | CRM + sales data |
| T+365 | Revenue closed from proposal-sourced leads, proposal accuracy (did we deliver what we promised?) | Revenue attribution |

### 10.2 Feedback Loop

Every T+90/180/365 check feeds back into the methodology:
- Underperforming claims → adjust marketing brief template
- Over-delivered features → adjust architecture scope
- Pricing pushback → adjust Financial model assumptions
- Legal objections → update Legal team brief

---

## 11. Pitfalls & Lessons Learned

### 11.1 v3.7 Postmortem

| Error | Root Cause | v4.0 Fix |
|-------|-----------|----------|
| Pricing table didn't match Financial model | Assembly agent used Marketing's numbers, not Financial's | **SOM Reconciliation Rule** (Section 5)  -  Financial is authority |
| Feature list referenced deprecated API | Architecture team wasn't re-dispatched when truncated | **Write to disk** for architecture (Section 4.1) |
| GDPR data residency omission | Legal team output was read but not integrated | **INSERT marker resolution** in assembly (Section 6.1) |
| CTA link pointed to staging | No cold-read QA before deployment | **Mandatory blind audit** (Section 7) |

### 11.2 v4.0 Discovered Issues

| Issue | Resolution |
|-------|-----------|
| Delegation summaries truncate at ~2K chars | Architecture team writes to disk. Other teams use concise HTML blocks with INSERT markers |
| Marketing SOM 6.5x higher than Financial | Enforced Financial authority during assembly |
| Architecture re-dispatch needed (first attempt truncated) | Now standard: architecture ALWAYS writes to disk |
| Budget tracking requires manual config rotation | Documented rotation protocol (Section 3.2) |

### 11.3 Recurring Pitfalls

1. **Forgetting to restore delegation model after dispatch.** Result: assembly burns Opus tokens at 50x the cost. Fix: always pair set + restore in the rotation protocol.
2. **Truncation blindness.** Delegation summaries only show ~2K chars. A 70K architecture document looks like it "completed" when it's actually 3% visible. Fix: architecture writes to disk always; other teams use concise outputs.
3. **Assembly agent trusting Marketing's numbers.** Marketing optimizes for persuasion. Financial optimizes for accuracy. Assembly must defer to Financial for all revenue figures.
4. **Skipping blind audit "because it looks fine."** v3.7 looked fine. It had 4 errors. The blind audit is non-negotiable.

---

## 12. Invocation Paths

### 12.1 Hermes (Sho'Nuff)

```
skill_view(name='verdicttank-proposal-pipeline')
```
Then follow the tier selection and dispatch protocol.

For methodology reference:
```
skill_view(name='verdicttank-proposal-pipeline', file_path='references/methodology.md')
```

### 12.2 Anita

Anita's profile has an identical copy of the skill:
```
~/.hermes/profiles/anita/skills/software-development/verdicttank-proposal-pipeline/SKILL.md
```

She invokes it the same way:
```
skill_view(name='verdicttank-proposal-pipeline')
```

### 12.3 Manual

The methodology is also available at:
```
/root/projects/itpp-infrastructure/proposals/verdicttank/methodology.md
```

---

## 13. Budget Model

### 13.1 Tier Costs (Actual v4.0 Run)

| Phase | Model | Cost |
|-------|-------|------|
| Research | DeepSeek V4 Pro | $0.05 |
| Marketing dispatch | Claude Opus 4.8 | $1.20 |
| Architecture dispatch | Claude Opus 4.8 | $1.35 |
| Financial dispatch | Claude Opus 4.8 | $0.90 |
| Legal dispatch | Claude Sonnet 5 | $1.10 |
| Assembly | DeepSeek V4 Pro | $0.15 |
| Internal conductor (critic) | Claude Sonnet 5 | $0.40 |
| Internal conductor (validator) | Claude Opus 4.8 | $0.55 |
| Blind audit | Claude Opus 4.8 | $0.49 |
| External conductor | Claude Sonnet 5 + Claude Opus 4.8 | $0.50 |
| **TOTAL** | | **$6.69** |

### 13.2 Budget Governance

- **Key:** `hermes-agent-v5` LiteLLM key
- **Cap:** $100/month
- **Per-proposal soft cap:** $10.00
- **Monitoring:** Check spend before dispatching tier 3 (`hermes keys usage hermes-agent-v5`)
- **Escalation:** If spend exceeds $75 in a month, pause all Tier 3 dispatches and notify Germaine

---

## 14. Quality Gates

| Gate | When | Who | Pass Condition |
|------|------|-----|---------------|
| Research complete | After Phase 1 | Main model | Market data sourced, competitors identified |
| Content delivered | After Phase 2 | Main model | All 4 team outputs received, architecture verified on disk |
| Assembly verified | After Phase 3 | Main model | SOM reconciled, INSERT markers resolved, consistency checks pass |
| Internal review | After Phase 4 | Sonnet + Opus | Average score ≥ 7/10 (Tier 2) or ≥ 8/10 (Tier 3) |
| Blind audit | After Phase 5 | Fresh Opus | 7/7 checklist items pass |
| External review | After Phase 6 | Fresh panel | Majority Go or Conditional Go |
| Deployment | After Phase 7 | Main model | All files served, all links resolve, analytics tagged |

**Stop rule:** If any gate fails, fix and re-enter at the failed phase. Never skip a gate to meet a deadline.

---

## 15. Document Governance

This methodology is **SETTLED**  -  it is the authoritative reference for all VerdictTank proposals. Changes require:

1. A specific, documented failure mode that the current methodology didn't prevent
2. A proposed amendment with before/after comparison
3. Germaine's approval before the amendment takes effect

**Version history:**
- v1.0 (2026-08-11): Initial methodology, encoding v3.7 postmortem and v4.0 build