by.waclaw.online / pm-agent / for leaders

The Product Manager Agent: The Leadership Case

Why an agentic assistant for requirements and documentation pays for itself on an internal-app team — in plain business terms, code-free. For the people who fund and staff the work.

If you read one thing. Two recurring taxes slow every internal-app team: requirements that arrive too vague to build without rework, and documentation that is never current enough to trust. Both are knowledge problems. We propose a pair of AI agents — an Analyst that interrogates fuzzy requests into testable stories, and a Librarian that keeps a living map of the system — built on the Jira and GitHub you already run. The goal is not to replace product managers; it is to delete the loops that make their work slow.

The two taxes we pay every sprint

Picture PromoDesk, an internal Trade Promotion Management app: key-account managers plan retailer promotions, the system books trade spend into a fund, and finance reconciles retailer deduction claims against what was promised. It is unglamorous, business-critical software — representative of the internal-app portfolio at any CPG company. Two things reliably go wrong, and neither is anyone's fault in particular.

Tax one: vague requirements

A request comes in: "We need better visibility into promotion spend." It sounds actionable. It is not. Does "spend" mean accrued, committed, or settled? Per account, per product, per promotion? Including or excluding unmatched deduction claims? Nobody decides up front, so the team builds something, demos it, and learns what was actually meant — in the most expensive possible place to learn it, after the code is written. The fix is another loop, then another. The requirement was never wrong; it was never pinned down.

Tax two: documentation rot

The antidote to vagueness is institutional knowledge: a clear picture of the data model, the screens, the batch jobs, the approval rules. Most teams have this written down somewhere — a wiki page, a slide deck, a tribal memory. It is almost always out of date, because keeping it current is everyone's responsibility and therefore no one's. So each new requirement is debated from scratch, and the same questions get re-answered every quarter.

The two taxes compound. Vague requirements persist because the documentation that would resolve them is untrustworthy. Rotten documentation persists because nobody has time, having spent it all on rework. It is a loop. The proposal below breaks it from both ends at once.

What we propose, in one picture

Two specialist AI agents, sharing one source of truth, wired into the tools the team already uses:

flowchart LR PM([Product manager / stakeholder]) --> ORCH["The PM Agent"] ORCH --> AN["Analyst<br/>pins down requirements"] ORCH --> LIB["Librarian<br/>keeps docs current"] AN --> JIRA[("Jira<br/>user stories")] LIB --> GH[("GitHub<br/>living documentation")] CAT["The catalog<br/>one map of the system"] -. read by both .- AN CAT -. read by both .- LIB

A thin front door routes to two specialists. Both read from one shared, living map of the system — so requirements and documentation finally reinforce each other instead of drifting apart.

The Analyst takes a fuzzy request and interrogates it — against what the system already does — until it is specific enough to build and to test. Its output is a clean Jira story with real acceptance criteria, linked to the parts of the system it touches. The Librarian owns the map: a catalog of the eight-to-twelve things that define the app (its data, screens, processes, rules, integrations), kept continuously current as a wiki rather than a frozen document. Crucially, the Analyst grills new requests using the Librarian's catalog, and the Librarian updates the catalog as the Analyst's stories ship. The loop that used to waste time now compounds knowledge.

What changes, concretely

TodayWith the PM Agent
"Better promo spend visibility" enters the backlog as one vague line.The Analyst asks the six questions that matter, cites the existing fund and claims rules, and produces a story a developer can start the same day.
The team discovers the real requirement in sprint review, after building the wrong thing.Ambiguities are surfaced before estimation, when changing your mind is free.
"How does the nightly accrual job actually work?" — nobody is sure; someone reads the code.The catalog answers in seconds, and it is trustworthy because the Librarian verified it after the last change.
A change to approval thresholds quietly breaks an assumption three screens away.The Analyst's impact scan flags every screen, batch job, and integration the change touches.
Documentation is a project you keep meaning to do.Documentation is a by-product of shipping, maintained by an agent that never gets too busy.

The case in numbers

You do not need heroic assumptions for this to pay off. The two taxes are well studied: requirements defects are the most expensive class of defect precisely because they are caught late, and a large share of rework traces back to unclear requirements rather than coding mistakes. The mechanism here is simple — move clarification earlier, and make the system's own knowledge cheap to consult.

Track a small number of honest metrics rather than a vanity dashboard:

Cost shape. The build is modest — you are configuring agents on top of Jira and GitHub, not buying a platform. The running cost is mostly model usage, which scales with how much elicitation and documentation work you route through it. Start with one team and one app; the marginal cost of adding the next app is small because the pattern, skills, and conventions are reused.

The honest risks, and how we contain them

RiskContainment
The agent invents a requirement or a fact about the system.The Analyst grills against the catalog and cites its sources; humans approve every story. The agent proposes; people decide.
The catalog itself drifts and becomes wrong — rot, just automated.Every entity carries a "last verified" date and an owner; the Librarian audits freshness and changes flow through review, exactly like code.
Teams feel surveilled or bypassed.The agent is a drafting assistant in the open — its work lands as Jira stories and GitHub pull requests that people edit and approve. Nothing is hidden or auto-merged.
It becomes shelfware.Adopt where the pain is sharpest (the messiest internal app), measure rework, and let results pull it into the next team rather than mandating it.

A pragmatic adoption path

  1. Seed the catalog (2–3 weeks). Point the Librarian at one app — PromoDesk — and have it draft the entity catalog from the code, the database, and existing docs. Humans review it into shape. You now have a trustworthy map for the first time.
  2. Turn on the Analyst (next sprint). Route new requests through grill-me before they are estimated. Measure clarification lead time and the questions it surfaces.
  3. Close the loop. When stories ship, the Librarian reconciles the catalog. Documentation freshness becomes a standing metric, not a project.
  4. Expand by pull, not push. When the first team's rework rate visibly drops, the second app is an easy yes. The conventions carry over.
Want the engineering detail? The builder track designs all of this concretely — the agent topology, the canonical entity catalog, the elicitation skills, the Jira and GitHub wiring, and a working Claude Code reference implementation. Start at The Problem or jump to The Entity Catalog.