- Core
- 45 min
- 6 min read
After this lesson you can
- Apply the nine governance rules to your catalogues.
- Separate confirmed facts, decisions, proposals and items to validate.
- Record a material change with owner, reason and affected sections.
- Use the completion checklist to decide whether a catalogue is finished.
Read these first
A catalogue that was true last quarter and nobody maintained is worse than none. It looks like knowledge and it misleads. Governance is the small set of rules that keeps the four layers true, owned and reviewed.
Why it matters
Catalogues fail slowly. A service is renamed, an owner leaves, an integration is switched off, and the page still says the old thing. Three months later an agent or a new colleague builds on it. Governance makes the failure visible early: every catalogue has an owner, a version and a next review date.
The nine rules
| # | Rule | In practice | TrailMug example |
|---|---|---|---|
| 1 | One current Master Catalogue per product | One file in git, one path | catalogue/master.md in the planning repository |
| 2 | Lower catalogues name their product and link to Master | Metadata header with a link | ORBITAL page links to master.md |
| 3 | Each catalogue has an owner and a review rhythm | Owner, version, last updated, next review | Owner: product manager. Review every quarter. |
| 4 | Separate facts, decisions, proposals and items to validate | Four labels in the text | “Fact:”, “Decision:”, “Proposal:”, “To validate:” |
| 5 | Do not call a plan operational until verified | Use PLANNED until evidence | The returns service stays PLANNED until it answers in production |
| 6 | Record material changes | Date, decision owner, reason, affected sections | Change note at the bottom of the page |
| 7 | Keep high levels short | Link runbooks and procedures | The row links the runbook, not its text |
| 8 | Never store secrets | Names only | EMAIL_API_KEY is named; its value is not |
| 9 | Report status with measures | Deliverables, evidence, blockers, owner, expected date | “ORBITAL: 7 of 7 elements done; blocker: budget owner; owner Maya; due 2027-04-15” |
Facts, decisions, proposals, validation
Use four plain labels so a reader knows what to trust.
| Label | Meaning | Example |
|---|---|---|
| Fact | Verified, with evidence | “The site is live. Opened 2027-03-02.” |
| Decision | Approved by a named owner, with date | “Use sender A. Decided by operations lead on 2027-02-03.” |
| Proposal | Suggested, not approved | “Proposal: move refunds to a weekly batch.” |
| To validate | A claim nobody has checked | “To validate: the CRM mirror is off.” |
Recording a material change
A change is material if it changes what exists, what it promises, who owns it, or what an agent may do.
| Field | Example |
|---|---|
| Date | 2027-03-18 |
| Decision owner | Product manager (placeholder: Maya) |
| What changed | Returns service moved from PLANNED to FOUND |
| Why | It answered a test request in production |
| Affected sections | Master row 3, ANDROID deployment record, Tech reliability |
Link the change record when the change touched production.
The completion checklist
A product catalogue is ready for review when all eight points are true.
- The Master Catalogue inventories repositories, services, addresses, types, purposes, dependencies, owners, access and findings.
- Entries are FOUND, NOT FOUND or PLANNED, with evidence or search scope recorded.
- ORBITAL defines all seven elements and connects the objective to measurable indicators.
- ANDROID covers all seven stages and names the relevant integrations, agents and deployment environments.
- Tech documents the shared foundation and the product-specific flavour.
- All catalogues are cross-linked, versioned, owned and reviewed.
- Proposals and assumptions are clearly separate from verified implementation.
- Credentials and secrets live only in an approved secret store.
Steps to apply governance
- Put the four pages in git, reviewed by merge request like code.
- Add the metadata header to each page.
- Name an owner. Use a CODEOWNERS file if your host supports it.
- Put the next review date in a calendar, not only in the page.
- At each review, mark every item Fact, Decision, Proposal or To validate.
- Run the checklist. Record the result in the change note.
- Search every page for secrets before merging.
Working with AI agents
- May: find pages past their review date, find terms that differ between layers, search for patterns that look like keys, draft change notes.
- May not: set a status to FOUND or Approved, change an owner, or merge a catalogue change on its own.
- Disclose: record which parts an agent drafted.
- A safe brief: “Search these four pages for text that looks like a password, key or token. Report file and line only. Do not print the value.”
Common mistakes
- No review date.
- An owner who is a team of ten. Name one accountable person.
- Facts and proposals mixed in one sentence.
- Changing a page without a change note.
- A secret pasted “just for now”.
- A checklist ticked without opening the evidence.
Practice
- Add owner, version and next review to your Master page.
- Label ten sentences from your catalogue Fact, Decision, Proposal or To validate.
- Write a change note for the last real change you made.
- Run the checklist on your own work and list what blocks approval.
The 2030 Product Development Manager lens
- You decide: the review rhythm, who owns what, and when a layer is approved.
- You delegate to agents: overdue-review reports, secret scans, cross-layer consistency checks, drafts of change notes.
- A sample brief: “List every catalogue page whose Next review date is in the past. Give path and date. Do not edit.”
- You verify by: reading the evidence behind two ticked checklist items.
- Disciplines involved: operations, security, compliance, product and finance.
- On the agent ladder: this page is govern. It is the written rulebook that lets you delegate and orchestrate without losing accountability.
Further learning
Next: metadata and fields, explained. Then see all nine rules applied in the full TrailMug example.
Go deeper
Further learning
Free or low-cost material from other publishers. We opened every link; check the cost label before you start.
Atlassian
Atlassian: IT change management (opens the publisher's site in a new tab)
- Free
- Article
- Intermediate
Describes ITIL-style change types such as standard, normal and emergency, and why teams classify changes. It uses traditional tools, so translate each idea into a merge request. Read it to understand the words auditors and large companies use.
Atlassian
ITSM: IT Service Management Definition, Benefits & Tools (opens the publisher's site in a new tab)
- Free
- Article
- Beginner
An introduction to IT service management and its practices: requests, incidents, problems, changes and the service catalogue.
GitLab
GitLab Docs: Code Owners (opens the publisher's site in a new tab)
- Free
- Docs
- Intermediate
Describes the CODEOWNERS file, which names the people or groups who must review changes to given paths. Use it to record who owns what, in git, next to the code. Pair it with approval rules for sensitive files.
GitLab
Merge requests (opens the publisher's site in a new tab)
- Free
- Docs
- Beginner
GitLab's reference for merge requests, the place where an agent's work is reviewed and merged. Read it so you can review agent output through the same door as any other change.
OWASP
Secrets Management - OWASP Cheat Sheet Series (opens the publisher's site in a new tab)
- Free
- Docs
- Intermediate
- about 30 minutes
Practical rules for storing, handing out and rotating passwords, keys and tokens. Read it before you let an agent touch configuration, CI or deployment.
Google
Google SRE Book: Embracing risk (opens the publisher's site in a new tab)
- Free
- Book
- Intermediate
A chapter that explains why perfect reliability is the wrong goal and how error budgets balance speed and safety. It is the base for the service level ideas in this program. Read it slowly; the ideas matter more than the maths.



