project-knowledge

What this skill does

# Project Knowledge

A routing guide for project knowledge. Each store has a different contract strength and purpose.

## Taxonomy

| Store | Location | Contract | Purpose |
|-------|----------|----------|---------|
| **Specs (reference)** | `specs/reference/` | Strongest | Source of truth for behavior. Gherkin scenarios. Verified before shipping. |
| **Specs (changes)** | `specs/changes/` | Provisional | Proposed changes not yet shipped. Intent, not truth. |
| **Docs** | `docs/` | Strong | Durable reference content. Maintained, authoritative, human-reviewed. |
| **Decisions** | `notes/DECISIONS.md` | Medium | Concise record of what was decided. One-liners with `dcn-xxxx` codes. |
| **Notes** | `notes/` | Weak | Working knowledge, scratch pages, topic clusters. May go stale. |
| **Journal** | `notes/journal/` | Weakest | Timestamped snapshots. Capture a moment. Decay over time. |

## Where Does It Go?

| What you have | Where it goes |
|---------------|---------------|
| Behavioral requirement with testable scenarios | `specs/` (reference or change spec) |
| Durable reference that should stay current | `docs/` |
| "We decided to use X instead of Y" | `notes/DECISIONS.md` |
| Working notes, research, topic exploration | `notes/` |
| Observation, discovery, gotcha, lesson learned | `notes/journal/` |
| Implementation plan for a feature | `specs/changes/NNN-slug/` |
| API documentation, user guide | `docs/` |
| Design rationale for a specific change | `specs/changes/NNN-slug/design.md` |

## Where Do I Look?

| Looking for | Check |
|-------------|-------|
| How something should work | `specs/reference/` first, then `docs/` |
| Why a decision was made | `notes/DECISIONS.md`, then `specs/changes/archive/` |
| Current project conventions | `CLAUDE.md`, `docs/` |
| Recent observations or discoveries | `notes/journal/` |
| Working knowledge on a topic | `notes/`, then `notes/journal/` |
| History of a feature change | `specs/changes/archive/` |

## Promotion Path

Knowledge flows upward in contract strength:

```
journal → notes → docs
                   ↑
journal → notes → specs/reference/
```

- A journal observation that proves durable → extract into `notes/` or `docs/`
- A notes page that becomes authoritative → move to `docs/`
- A decision that needs behavioral enforcement → add Gherkin scenarios to `specs/`
- A completed change spec → merge scenarios into `specs/reference/`, archive the change

## Relationship to Other Plugins

This plugin provides routing guidance. The actual stores are managed by:

| Store | Plugin |
|-------|--------|
| `specs/` | **spec-driven-dev** – structured workflow with proposals, Gherkin specs, design, and archive |
| `notes/`, `notes/journal/`, `notes/DECISIONS.md` | **project-notes** – conventions for notes, journal entries, and decision log |
| `docs/` | No plugin needed – standard project documentation |

## Rules

- Don't duplicate knowledge across stores. Each piece of information lives in one place.
- Link between stores using `[[wikilinks]]` or relative markdown links.
- When in doubt about where something goes, check the taxonomy table above.
- Specs have the strongest contract: if a Gherkin scenario says it, the code must satisfy it.
- Docs have a strong contract: if it's in `docs/`, it should be current and maintained.
- Journal has the weakest contract: entries may be stale. Check recency and promotion status.