How each person on a product team uses one spec

A spec that spans several repositories is not one document that everyone reads the same way. It is one source of truth that six different people open to find six different things. The product manager wants to know the feature is described correctly. The developer wants to know what lands in their repository. QA wants the test scenarios. Hand all of them the same PDF and most of them are skimming for the one section that is theirs.

The mistake is treating that as a documentation problem — write it better, add headings — when it is a structure problem. Each role has a different job to do with the same underlying facts, and the artifact only works if it serves each of those jobs without forcing everyone to read the whole thing.

The shared thing is the context, not the document

What every role actually depends on is the same underlying map: which repositories the feature touches, how the services connect, and where each claim comes from in the code. A product manager who cannot enumerate the affected services, and a developer who does not trust the task landing in their queue, are suffering from two symptoms of one missing thing — a shared, source-anchored view of the work.

That is why the design goal is a single generated artifact with the evidence attached, not a stack of role-specific documents that drift apart. When the technical section cites a file, a line, and a commit, the tech lead can verify it instead of arguing about it. When the same underlying analysis produces the product doc and the task breakdown, the developer's tickets and the PM's spec cannot quietly disagree, because they came from the same reading of the repositories.

What each role does with it

• Product manager — writes the request, approves the result. They start it: the feature in plain language, no repository knowledge required. They answer the tool's questions, edit the generated product document, and approve it. Their measure of success is narrow and honest — the spec is accepted by engineering without a major rewrite.
• Engineering manager — reads the shape and the scope. They want the architecture overview, the list of affected repositories, and the per-repo breakdown of work, so an estimate rests on the real surface area of the change rather than a guess. They are usually the one approving that the task structure is sane before anything leaves for the tracker.
• Tech lead — validates the claims. Their job is not to read the spec but to check it: follow the source references to the actual file and line, correct an inference the analysis got wrong, and close the open questions. This is the role the whole design leans on — the reason claims are anchored to code is so a tech lead can verify them in seconds instead of relitigating them in a meeting.
• Developer — reads only their repository. They open the tasks that fall to the repo they own: the file references, the API and data-model changes, the specific work. They should not have to read the other three services' sections to find the paragraph that is theirs.
• QA — takes the test plan. They work from the test scenarios and the acceptance criteria to decide the regression scope. When those come from the same analysis as the spec, the thing being tested and the thing being built are the same thing.
• Solution architect — checks fit. For customer-facing technical work, they use the service map to see whether a request fits the system that exists, and share the technical document as the answer.

Access is a separate question from role

How a person uses the spec is not the same as what the system lets them do. Job titles are not permissions — the tool does not have a "developer" or "QA" role. The permission model underneath is deliberately small: within a project you are an owner, an admin, a member, or a viewer, and that is the whole list.

Two parts of that are worth calling out because they shape how a team adopts it:

• Approval is held back on purpose. Editing a document is a member's right; approving one is not. Approval is the gate in front of an outward action — writing to your Jira — so it sits with owners and admins, not with everyone who can type. The point at which the tool touches another system is the point where a named person has to say yes.
• Reading is free; editing is the seat. A viewer can read everything the project holds — the documents, the architecture, the search — but starts no jobs and writes nothing, and does not consume a paid seat. So the tech lead who only ever validates, the manager who only reviews, and the stakeholder who only wants to see the plan are not a per-head cost. You pay for the people who generate and edit, not for everyone who needs to look.

The result is one artifact that six roles use differently and a permission model that keeps the outward-facing decisions with the people accountable for them. A spec is not more useful because everyone reads all of it. It is more useful when each person can trust the slice that is theirs — and follow it back to the code when they don't.