PM Knowledge-Base Workspace

The problem

A complex, multi-surface PM job — multiple workstreams, dozens of specs at different maturity stages, evidence and claims that have to stay traceable across quarters, decisions that need to survive personnel changes — does not stay coherent on its own. By default it fragments across tools (tickets here, decks there, meeting notes in a fourth place), sources of truth quietly diverge, and context evaporates between sessions. Adding an AI agent on top of the fragmentation accelerates the rot rather than fixing it: the agent gets confidently wrong because the knowledge it's drawing from is itself stale.

The workspace is the operator's answer to that. It's not a shipped product and not a client deliverable — it's the system I use to keep my own PM work coherent across sessions, environments, and weeks, and to give an agent enough structure that "human curates, model maintains, knowledge compounds" actually holds up under daily use.

The shape, top-level

~400 files across eight areas, all under one git repo:

• .cursor/rules/ — seven always-loaded .mdc rule files that every session inherits. Current-state pointers, architecture facts, file-layout conventions, agent session lifecycle, the failure taxonomy, prose conventions, skill routing.
• reference/ — institutional memory. Long-lived knowledge that changes slowly: primers, research, roadmaps, product-context docs, meeting notes.
• planning/ — the working layer, organized by [year]-Q[n]/pods/[pod]/. Quarter's rocks, scorecards, annual goals, competitive analysis, positioning brief, session notes, spec directories.
• skills/ — eight skill packages. Each is an agent capability with a defined trigger, a specific input set, and a specific output set.
• services/kb-api/ — a local FastAPI + SQLite service that mirrors the knowledge graph and filesystem into a queryable DB.
• scripts/ — derivation utilities (manifest generation, reference-index generation, cowork-instructions generation, graph-navigation benchmarks, health checks).
• .claude/ — gitignored. Per-machine permission allowlists and scheduled-task references.
• Root files — CLAUDE.md (workspace config), graph.yaml (the knowledge graph), MANIFEST.md (auto-generated file inventory).

The knowledge graph

The distinctive architectural choice: a single graph.yaml at the workspace root is the primary navigation and dependency model. Everything else derives from or defers to it.

It's not a flat edge list. It's a typed five-layer structure: content (topics and their artifacts), governance (which files are authoritative, what confidence they carry, what propagates when they change), activation (workstreams that group topics by purpose rather than ownership), outcome (evidence and claims with explicit evidence classes — verified, supported, asserted — and upgrade conditions), and learning (insights derived from evidence that cross multiple topics).

The graph supports two traversal axes: a question about a feature enters through topics; a question about purpose or capability enters through claims or workstreams. Both axes reach the same artifacts via different paths. The routing rules specify which axis is correct for which question shape, so "what does the platform enable" returns a different answer than "what are we working on" — exactly as it should.

Most artifacts don't need to be declared in the graph. A file in specs/{topic_id}/ automatically belongs to that topic, with its role inferred from filename (spec-v1.md → role spec; feature-ticket.md → role ticket). Only cross-cutting artifacts get explicit declarations. This keeps the graph small enough to hold in a human's head while staying complete.

A separate script runs 31 deterministic navigation queries across 11 categories — topic lookup, hierarchy traversal, spec folder convention, authority propagation, evidence resolution, claim tracing, workstream membership, relationship traversal, foundation indexing, full multi-step paths, insight integrity. Unlike usage logging, the tests are instant, repeatable, and don't depend on agent compliance. They run after every graph edit and as part of the weekly health check.

Skills

Eight skill packages in skills/, each with a trigger set and a clear input/output contract:

• Spec workflow. Multi-agent pipeline. A response agent researches context, an interviewer runs a six-phase structured interview that pushes for precision, a spec writer transforms the interview into a structured document, a product critic scores the spec against quality gates, and a delivery critic scores for buildability across six dimensions. Interview state persists so sessions can resume.
• Strategic planning. Four coaching modes — goal setting, rock drafting, rock critique, scorecard design — that push from activity lists to outcome-driven strategy.
• Blast radius. Downstream impact analysis. Given a changed file, traverse graph authority and propagation chains, topic co-membership, and evidence-touches to rank every file that likely needs review.
• Answer propagation. Conversational KB updates. The operator reports findings in natural language; the skill matches them to tracked items (research-agenda unknowns, action items, claims) and proposes the exact edits. The operator approves. The operator never hand-edits these files.
• Spec-table reporting. Scans spec folders, computes maturity stages, emits a summary spreadsheet.
• Spreadsheet formatter. Two output shapes — lean internal, full shared — sourced from the same canonical rocks document.
• Ticket reader. Browser-automation integration that reads status metadata from the operator's authenticated session in an internal tracking tool and summarizes across a batch.
• Product-analysis vetting. Cross-checks analyses against the evidence index to flag claims that haven't been grounded.

The KB API service

services/kb-api/ is a local FastAPI + SQLite service that mirrors graph.yaml and the workspace filesystem into a queryable database.

Why it exists: agent-readable graph navigation is fine for single questions, but for higher-frequency operations — coverage analysis, proposal generation, health checks — reading and parsing a 1,000-line YAML per query is slow and wastes context. The service loads the graph once into SQLite and answers via REST in milliseconds.

It exposes /sync, /context (a compact session briefing for agent startup — coverage stats, pending proposal count, graph summary, last sync time, in a single response that's an order of magnitude smaller than reading the raw planning files), /coverage (files tracked, inferred, or orphaned), /proposals (structural suggestions for graph additions, each with approve/reject/defer state), /health, /topics/{id}, and /blast-radius/{path}. The stack is Python, FastAPI, SQLite from stdlib, PyYAML, uvicorn — nothing else.

PM Intelligence Stack

A five-level failure taxonomy that structures what the daily and weekly review routines look for. Each level catches a different class of thing that goes wrong in a complex knowledge-work job.

Each level has a canonical artifact. A research agenda tracks L4 unknowns; a positioning brief tracks L5 claims with evidence classes; the weekly coherence block in the session-continuity file tracks L3.

The Top 3 rule. The daily planner doesn't just list everything open — it forces a ranked top three with one item per band (Execution L1/L2, Coherence L3, Intelligence-Narrative L4/L5). A plan that's all-L1 means the week is about to lose coherence. A plan that's all-L5 means nothing will ship. The rule is an opinionated constraint that surfaces the balance problem before it becomes a regret.

This taxonomy is the most transferable part of the whole workspace. It works for any knowledge-work role where execution and strategic coherence both have to be maintained — not just PM work.

Three-environment workflow

The workspace is edited from three places by the same operator:

• Cursor IDE — interactive sessions. Rules auto-inject.
• Claude Code (terminal) — scripting, git operations, background tasks. Reads rules via CLAUDE.md pointers.
• Claude Cowork (desktop) — scheduled tasks, autonomous multi-step work, file organization. Reads both CLAUDE.md and per-project instructions derived from the same rule files.

Divergence prevention. All three environments commit to main only. Side branches are forbidden at the practice level — not technically enforced, a discipline. On session start, each environment runs git branch --no-merged main and git status --short to detect uncommitted work from one of the others and flag it before starting new work.

Single-source derivation. The rule files and the graph are canonical. The Cowork Project Instructions are generated from them by a script, not maintained separately. The reference-folder README is generated from the graph's foundation index, not hand-edited. There is one copy of every fact; the rest are derived.

What I'm proud of

The five-level failure taxonomy and the Top 3 rule. Most personal-productivity systems fail because they don't make the operator confront the balance between execution, coherence, and intelligence work — they let you spend the whole week on L1 fires and call it productivity. The Top 3 rule turns that into a visible, daily decision: at most one item from each band, ranked, and the imbalance shows up immediately if the week is drifting.

Authority + propagation as a layer of the graph instead of frontmatter on every file. The earlier shape of this workspace had source_of_truth, downstream, and derived_from fields scattered across ~40 files. Pulling all of that into one declarative governance layer in graph.yaml made authority visible at a glance, made blast-radius computable in one pass, and removed an entire category of "two files disagreeing about who's authoritative" bug.

The KB API service as a startup-context endpoint. /context in particular — instead of an agent starting a session by reading 30+ planning files and burning thousands of tokens reconstructing where things stand, it hits one endpoint and gets the structured answer in a fraction of the context budget. That single decision changed how often session-start friction kills a useful working block.

What this is evidence of

The workspace is the operator's comprehension layer made into a system. Every pattern in it exists because, at some point, I noticed that without it a specific class of thing would be missed — an L4 unknown would age into an L5 liability, a source-of-truth edit would leave seven dependent files stale, a rock would drift from its scorecard without triggering a review. Each piece of the architecture is a generalized answer to "this almost got past me once."

The comprehension checklist in the lab repo is an abstract version of the same claim. This project is the concrete, lived version of it — the one that shows what the abstract claim looks like when it's implemented as a working system over months of daily use.

Why there's no live link

The workspace is intentionally private. The employer, the product, the pod, the competitive context, customer names, and every word inside graph.yaml would all leak strategy structure if they were public — so they aren't. What is public is the functional architecture itself: the rule shapes, the graph layers, the skill contracts, the API surface, the failure taxonomy, the lifecycle protocol. Those are the transferable artifacts, and they live in full at github.com/cessnajim/inflectionpt-lab/projects/pm-kb-workspace as part of the Inflection Point Advisory lab — public method, private source.