Engineering to Knowledge Base: Project Capture, Scope v1

1. Scope

This design covers only how engineering projects enter a knowledge base. It does not design a skills system, a general taxonomy of technical capabilities, later enablement loops, or agent workflows. It is the first entry layer of a broader knowledge system.

2. Goal

Create a repeatable path for code changes, feature evolution, and architectural changes to become structured knowledge assets. The immediate questions are how to capture existing projects and how to keep up with future changes.

3. Project Structure

knowledge-base/
  project-name/
    commits/
    features/
    architecture/
    decisions/     # optional

commits/: Time-Based Events

One file per engineering change, based on the commit message and date, with a diff when useful. This records what happened and supports historical review or ongoing capture. It should not become the permanent description of a capability.

features/: Long-Lived Functional Capabilities

One file per user-facing capability, updated as its behavior changes. A new feature, improvement, or business-rule change updates the relevant feature file rather than adding another time-stamped description.

architecture/: Long-Lived Structural Capabilities

These files describe module boundaries, data flows, caches, messaging, data models, and security mechanisms such as signatures. Architectural or data-flow changes update the corresponding document.

decisions/: Optional Major Decisions

This directory is not mandatory. It records architectural turning points, significant technology choices, or changes in strategy when those decisions warrant a separate record.

4. Existing and Future Projects

For an existing project, do not attempt to reconstruct every historical commit. First describe the current architecture and features, then review only key commits. The result should be a useful picture of the system today.

For each future engineering change, record the commit event, check whether a feature or architecture document needs updating, and add a decision record only when appropriate.

5. Principles

1. Separate time-based events from structural descriptions.
2. A commit is an event, not a capability.
3. Feature and architecture documents are long-lived entities.
4. Do not require a complete decision history.
5. Improve the structure incrementally.

The design intentionally stops at the project-to-knowledge-base boundary. Later work might extract skills from the knowledge base or use those skills for technical decisions, but neither is in this version's scope. The immediate goal is a capture structure that can be maintained consistently, not perfect historical documentation.