How To Use The KB

This repo is Datopian's lightweight company knowledge base and portfolio tracker.

Use it to answer three practical questions:

what are we currently working on
how is that work structured
where is the canonical page for a given initiative or project

Start here

If you are new to the repo:

Open portfolio/README.md
Use the portfolio tree as the main overview
Open the initiative or project page you want to understand
Use the template docs only when you are creating or updating a page

What lives where

Initiatives

Initiatives are the long-lived things:

products
services
internal systems
capability areas
grouping initiatives

They live in initiatives/.

Projects

Projects here are major internal improvement efforts: developing a product, building an internal process, or growing a company capability, such as E2E operators, the PortalJS go-to-market push, or the company KB rollout. They live in projects/, as a single markdown file or, when they have supporting material, a folder with a README.md. Start with How to run a project.

Client delivery is tracked elsewhere and does not belong here. Campaigns, monthly cycles, routine operations and product releases belong in their execution trackers. Keep a concise summary and a tracker link on the initiative rather than adding a project page here. Historical records retired from this portfolio live in the repo-only docs/plans/retired-projects/ folder.

Portfolio views

The portfolio views are the navigational layer:

portfolio/portfolio-indented.html
portfolio/portfolio-map.html

They are generated from the markdown files in initiatives/ and projects/.

The tree is the default view. The map is optional.

Initiative or project?

Use an initiative if the work is ongoing.

Use a project only when the work is a major internal improvement (product, process or capability, not client delivery) with an objective and a date by which we will know whether it worked. A deadline alone does not qualify an effort for a project page.

Where SCQH and plan fit

Default rule:

SCQH belongs at the initiative level
projects get an LTP analysis (the skill can interview you from scratch) plus a plan of work

See How to run a project.

Minimum required information

Initiative minimum

Every active initiative should have:

title
owner
status
north_star
scqh
next_step
commitment
target_date
active_issue

If it sits under another initiative, add parent.

If it has active child projects, link them in the body of the page.

Project minimum

Every active project should have:

title
owner
status
parent
hypothesis
success_metric
definition_of_done
end or a clear timebox
active_issue

The body starts with a ## Summary answering: objectives and key results, analysis (LTP or SCQ, linked), driver, and timeline. Use the rest for updates, evidence, related issues, and notes.

Quality rule

No active project should exist without:

a Summary answering objectives and key results, analysis, driver and timeline
a clear hypothesis
a clear success test
a clear done definition
a clear end date or review point
one canonical live issue

No active initiative should exist without:

a concrete commitment
a target date
one canonical live issue

Learning rule

Every finished or paused project or experiment should capture:

what we tried
what happened
what we learned
what we do next, if anything

How to add or update pages

Add a new initiative

Create a file in initiatives/
Use docs/initiative-template.md
Fill in the minimum fields
Add only the body sections that are actually useful
For active initiatives, include ## Current Commitment, ## Key Results, ## Milestones, and ## Related Issues

Add a new project

Follow How to run a project. In short:

Confirm it is a major internal improvement, not client delivery
Create the page from docs/project-template.md, with a clear parent initiative
Run the LTP skill; it asks questions to get started, so no SCQ is needed first
Fill in the ## Summary (objectives and key results, analysis, driver, timeline) and the minimum fields
Put actions in a beads epic and set active_issue
For active projects, include ## Summary, ## What this project is, ## Plan of work, and ## Related Issues

Update an existing item

edit the existing page directly
keep that page as the source of truth
avoid duplicating the same information elsewhere

Practical rules

keep the portfolio tree lightweight and navigational
keep richer detail on the item page itself
avoid duplicate overview docs
prefer concrete names over vague bucket names
every project should have a clear parent
keep templates lightweight, but not rushed
if a project cannot be assessed at the end, the template is too light
if an initiative cannot say what it is promising by when, it is not ready to be active

Accountability rule

The KB is not just descriptive. It is meant to support commitments.

That means:

active items should be reviewable at any time
owners should be able to explain whether they are on track
the CEO should be able to inspect promise, date, milestone, and issue quickly

Use portfolio-accountability-rhythm.md when running the team review or resetting the portfolio.

README.md
projects/README.md
portfolio/README.md
docs/initiative-template.md
docs/project-template.md
docs/portfolio-accountability-rhythm.md
portfolio/structure-rationale.md

Repository versus published site

Retained company knowledge is published. Delete obsolete drafts, abandoned workstreams and superseded duplicates rather than hiding their folders. Preserve useful outcomes and source links on the relevant initiative when removing a duplicate.

Publication exclusions are for material that supports working in the repository: agent instructions, tooling, task tracking, internal plans and handoffs in docs/plans/, and social-skill context/examples. An exclusion is a deliberate retention decision, not an archive for irrelevant content. The retained dated meeting and client-feedback records are evidence, not current task lists.

Useful company references include distribution locations, launch submission requirements, the anchor-moment process, and its dated cycle log.