LLM Execution Model

How LLMs and humans collaborate on documentation updates.

---

Principle: LLM-Driven, Human-in-the-Loop

Default: LLM executes autonomously using code, docs, and patterns as sources of truth.

Human involvement: Only for review gates and high-value questions that can't be answered from available sources.

---

When LLM Proceeds Autonomously

LLM Can Execute Without Human

Task	Sources LLM Uses
Identify code changes	git diff, git log
Map changes to SRS domains	Domain mappings (archived: PASS_C_DOMAIN_MAPPING.md)
Extract inventories (schema, events, jobs)	Code analysis
Write new requirements	SRS templates + code analysis
Update SDD sections	Existing SDD patterns + code analysis
Update code_tags.json	code_tags.json structure + existing entries
Add Implementation sections	Code boundary analysis
Run validation scripts	Automated checks
Create Change Manifests	git + PRD analysis

LLM Decision Framework

Can I find the answer in code? -> Yes -> Proceed
Can I find the answer in existing docs? -> Yes -> Proceed
Is this a pattern we've established? -> Yes -> Apply pattern
Does this require product/business context? -> Yes -> Ask human
Is this a subjective/policy decision? -> Yes -> Ask human

---

When to Involve Human

Review Gates (Human Must Approve Before Continuing)

Gate	What Human Reviews	When
Change Manifest	Completeness, missed items	After Phase 1
Impact Analysis	Correct SRS/SDD mapping	After Phase 2
New Requirements	Statement, ACs make sense	After Phase 3
Architecture Changes	Design decisions	After Phase 4
Final Validation	Sign-off on release	After Phase 7

Escalation Triggers (LLM Asks Human)

Situation	Example	What to Ask
Business logic unclear	"Why does this rule exist?"	"What is the business reason for X?"
Conflicting sources	Code does X, doc says Y	"Which is correct: code or doc?"
Missing context	No doc or code explains behavior	"What should happen when X?"
Policy decision	Multiple valid approaches	"Which approach do you prefer?"
External knowledge	Customer requirement, compliance	"Is there a constraint I should know?"
Deprecation decisions	Should feature be removed?	"Confirm deprecation of X?"

What NOT to Ask Human

Don't Ask	Why	LLM Should Instead
"Is this requirement format correct?"	Template exists	Follow SRS templates
"Where should I add the code mapping?"	Pattern exists	Follow code_tags.json structure
"How do I structure the SDD section?"	Pattern exists	Follow existing SDD sections
"What's the next REQ ID?"	Computable	Count existing IDs
"Does this code implement the requirement?"	Analyzable	Read code and determine

---

Parallelization Patterns

From Learned Experience (archived: CODE_REVIEW_PLAN.md)

Pass A (Gap Closure): Schema gaps || Behavior gaps

• GAP-013+017 (schema) ran parallel to GAP-027+028 (runtime)

Pass B (Inventories): All 6 inventories are independent

• DB Schema || Events || Integrations || Jobs || Auth || Audit

Pass C (Backend Linking): By domain, in waves

• Wave 1: Auth/User Management
• Wave 2: File Import
• Wave 3: Rules & Analytics
• Wave 4: Audit
• Wave 5: Remaining domains

Pass D (Frontend): By component type

• Page components || Feature components || Composables

Applying to Version Updates

Phase	Parallelizable?	Pattern
Change Detection	Partially	Code areas can be analyzed in parallel
Impact Analysis	No	Requires complete change manifest
SRS Updates	Yes	One agent per domain
SDD Updates	Partially	Independent sections in parallel
Code Mapping Sync	Yes	One agent per domain/module
Validation	No	Requires all updates complete

---

Agent Task Structure

When spawning agents for parallel work:

Critical Rule (from CLAUDE.md): Never send multiple docs for conversion to a single subagent. Each agent should be responsible for a single file output. Instead of "convert these five files," launch 5 separate agents.

Single-Domain Agent

Task: Update SRS for {domain}
- Read: docusaurus/docs/srs/{domain}.md
- Read: Domain mappings (archived: PASS_C_DOMAIN_MAPPING.md) for code boundaries
- Analyze: Code changes affecting this domain
- Write: Updated SRS file
- Output: Summary of changes made

Inventory Extraction Agent

Task: Extract {inventory_type} inventory
- Scan: Relevant code paths (from archived CODE_REVIEW_PLAN.md)
- Document: Items found with locations
- Output: Inventory data for SDD merge

Code Mapping Agent

Task: Update code_tags.json for {domain}
- Read: Domain mappings (archived: PASS_C_DOMAIN_MAPPING.md) for boundaries
- Read: docusaurus/docs/srs/{domain}.md for REQ IDs
- Update: tests/catalogue/code_tags.json (all three views: by_file, by_srs, by_sdd)
- Update: Implementation section in SRS
- Output: Count of entries added/modified, validation results

---

Evidence and Audit Trail

LLM Must Document

What	Where	Format
Decisions made	Reviewer Notes in SRS	Markdown
Code findings	Evidence log	Date, location, finding
Human responses	SESSION_HANDOFF	Q&A format
Validation results	VALIDATION_CHECKLIST	Pass/fail

Evidence Log Entry Format

From archived CODE_REVIEW_PLAN.md:

## {Date} - {Gap ID or Change ID}

**Verified:** {What was checked}
**Code Location:** {File path + method}
**Finding:** {What was found}
**Doc Update:** {What changed in SRS/SDD}
**Code Update:** {code_tags.json updated? Y/N}
**Confidence:** High / Medium / Low

---

Session Handoff

When session ends or context limit approaches:

# SESSION_HANDOFF

## Status
- Phase: {Current phase}
- Completed: {What's done}
- In Progress: {Current task}
- Remaining: {What's left}

## Human Decisions Needed
- [ ] {Question 1}
- [ ] {Question 2}

## Files Modified This Session
- {file1}: {what changed}
- {file2}: {what changed}

## Next Session Start Point
{Exact instructions for resuming}

---

Summary: The 80/20 Rule

80% LLM-driven:

• Code analysis
• Pattern application
• Document generation
• Validation execution
• Inventory extraction

20% Human-in-the-loop:

• Review gates (approval before proceeding)
• Business/product questions
• Conflict resolution
• Policy decisions
• Final sign-off