DocAgent: Automated PHPDoc Generation via Surgical Patch Injection

DocAgent is the simplest of the five core LIMAgents agents. It reads code, understands it, and writes documentation. No tests to run, no patches to validate, no branches to manage — just read and document.

Tool Set

read_file       → Read the code to document
grep_codebase   → Find related code, callers, implementations
list_files      → Discover what needs documentation
write_file      → Create new doc files (README, API docs)

Notably absent: generate_patch and bash. DocAgent writes documentation as new files or as modifications to existing files via write_file. For adding PHPDoc to existing methods, it reads the file, constructs the documented version, and writes it back.

Config

max_iterations: 20
model profile: 'fast'     // Documentation is formulaic
temperature: 0.3
approval_mode: 'auto'     // Docs don't need approval gates

Auto-approval because documentation changes are low-risk. A bad PHPDoc comment doesn't break production. A missing @param doesn't crash the application.

Twenty iterations sounds generous for "writing comments," but a single DocAgent run often walks an entire directory: list_files → read_file for each candidate → write_file with the documented version → repeat for the next file. Each documented class is ~2–3 iterations, so 20 lets DocAgent handle a mid-sized directory in one run without hitting the cap.

What DocAgent Produces

PHPDoc blocks — for methods, classes, and properties:

/**
 * Execute the agentic loop: prompt → AI → tool calls → repeat.
 *
 * Continues until: end_turn, successful generate_patch,
 * max iterations, token budget exceeded, or cancellation.
 *
 * @param AgentConfig $config Immutable execution configuration
 * @param string $prompt User's task description
 * @param callable|null $onProgress SSE progress callback
 * @return AgentResult Immutable execution result
 */
public function run(AgentConfig $config, string $prompt, ?callable $onProgress = null): AgentResult

README files — module overviews, API documentation, architecture guides.

Configuration documentation — what each config option does, default values, valid ranges.

Quality Rules

DocAgent's system prompt includes rules about what makes good vs bad documentation:

Good PHPDoc:

• Explains why, not just what


• Documents non-obvious parameters


• Includes @throws for thrown exceptions


• Notes side effects (file writes, database changes, event firing)

• Restates the method name: /* Get user / public function getUser()


• Documents obvious types: @param int $id The ID (the type hint says this)


• Uses vague descriptions: @return array The result

The Documentation Tradeoff

Automated documentation has a specific sweet spot:

Good for: PHPDoc on all methods (comprehensive coverage), README updates after refactoring, API endpoint documentation, config file documentation.

Bad for: Architecture decision records (ADRs), design rationale, "why we chose X over Y" narratives. These require human context that no code analysis can provide.

DocAgent handles the first category — the 80% of documentation that's about what the code does. The 20% about why remains human work.

Up Next

Next up: LukAgent: From N+1 Detection to Git Branch in One Event Chain — the healing agent that reads detection data, generates patches, and triggers the approval workflow.