Docudoodle Laravel Package

Product Decisions This Supports

• Build vs. buy for documentation tooling. At MIT license, a single composer require, and zero bespoke infrastructure, this collapses a "should we build an internal doc generator" conversation into a one-week evaluation spike. The alternative — an internal tool — would cost engineering weeks and need ongoing ownership.
• Onboarding and knowledge-transfer roadmap. The strongest use case is inherited or undocumented Laravel applications. This maps directly to a measurable OKR: time-to-first-merged-PR for new engineers. Generating a Markdown doc set in a repo before a new hire's start date is a cheap, visible intervention.
• Tech due diligence and acquisitions. For a PM inheriting a codebase (acquisition, reorg, contractor handoff), running this once produces an artifact you can read and share with stakeholders in an afternoon — de-risking estimation before committing roadmap scope.
• Feature-level "definition of documented." The caching plus orphan-cleanup design means docs can be treated as a build artifact that stays in sync rather than a one-off deliverable. That supports a policy decision: require a doc top-up run as part of a feature's definition of done, at near-zero marginal cost since only changed files are reprocessed.
• Vendor and data-residency decisions. Multi-provider support (OpenAI, Azure, Claude, Gemini, Ollama) turns "can we use AI on our code" into a standard procurement question rather than an architectural one. Ollama support unlocks adoption where code cannot leave the network; Azure unlocks enterprise compliance review.
• Documentation distribution strategy. File output, Jira issues, and Confluence pages as interchangeable sinks lets you meet stakeholders where they already work, rather than forcing a new tool into the org.
• Cost forecasting for AI-assisted tooling. The config-hash and content-hash cache design makes LLM spend predictable and explainable per PR — a useful data point when arguing for or against broader AI tooling budgets.

When to Consider This Package

Adopt when:

• The stack is Laravel/PHP and will remain so; this is not portable to other ecosystems.
• You have low or zero existing documentation and need coverage now, not a perfectly curated doc site.
• Your dominant need is explanatory/narrative documentation (what does this class do, how do these services interact) rather than deterministic API reference output.
• You can tolerate human review of generated content — treat output as a first draft for engineers, not published customer-facing docs.
• Data residency is a hard constraint but a local Ollama model is acceptable in quality terms, or Azure OpenAI is already approved.
• Cost sensitivity is high and the delta-only caching behavior matters — i.e., an established repo where most files are unchanged run-to-run.

Look elsewhere when:

• You need deterministic, spec-accurate output: OpenAPI generators, phpDocumentor, or IDE-grade static analysis will beat an LLM on signature-level accuracy.
• The codebase is enormous or has tight per-run cost ceilings; broad file-extension scanning multiplies token spend and needs guardrails before the first full run.
• You need a governed docs pipeline — review workflows, versioning per release, approval gates, ownership assignment. This generates files; it does not govern them.
• Non-PHP is the primary target. YAML support exists, but the value proposition is PHP-shaped.
• Adoption risk tolerance is low. The package has 163 stars and 0 dependents — essentially unproven in production at scale. Recent releases show healthy maintenance (Laravel 13, PHP 8.5), but there is no ecosystem evidence of long-term reliability. If documentation becomes a load-bearing part of your onboarding or compliance story, you must be willing to fork it under MIT or own the fallback.
• Prompt injection or secret-leakage risk is unacceptable without controls — source content is sent to a third-party model, and configuration files, env vars, or credentials in scanned paths could be included. Budget time for skip-directory hygiene and a pre-flight audit of what gets sent.

Also flag for evaluation: LLM-generated diagrams and architectural claims can be confidently wrong. Never let generated content reach an external audience without an engineer's sign-off.

How to Pitch It (Stakeholders)

To executives: This is a low-cost, MIT-licensed tool that reads our Laravel code and writes the documentation we keep not writing. It runs as a single Artisan command, costs a few cents to a few dollars per run depending on model choice, and only reprocesses files that changed — so the cost of keeping docs current is near zero once the first pass is done. The primary business outcome is onboarding speed: a new engineer or an inherited codebase goes from "read the code and guess" to "read the docs and ship." It also gives us a defensible answer on data residency, since it can run entirely on local models or through our approved Azure tenant. Risk is genuinely low: no new infrastructure, no schema changes, no runtime dependency in production, and removing it is a composer remove.

To engineering: One composer require and one command. It scans configured directories, skips vendor/node_modules/tests, hashes each file, and calls the model of your choice — OpenAI, Claude, Gemini, Azure, or a local Ollama instance. Reruns only touch changed files and clean up docs for deleted source files, so it fits a post-merge or CI slot without becoming a maintenance burden. Prompt templates are plain Markdown with simple variables, so you control the output shape, and output can go to the repo, Jira, or Confluence. The honest caveats: treat output as a reviewed draft, not ground truth; audit skip directories before the first run so nothing sensitive is sent to a third-party API; and because the project has a small user base, we should pin the version and be prepared to fork it if it stalls. Recommend a two-week spike on one legacy service, measured against how much a mid-level engineer actually trusts and reuses the output.