decision-log

What this skill does

# Decision Log

Record project decisions to the context-hub so they survive context resets and session boundaries. Every decision entry captures *what* was decided, *why*, *what alternatives were considered*, and enough telemetry to reconstruct the moment.

## When to Log

**Explicit:** User says "log this decision", "record decision", "capture decision", "ADR", or similar.

**Proactive:** When you detect a meaningful decision was just made — a choice between alternatives, a tradeoff accepted, a direction confirmed. Suggest it briefly:
> "Worth logging this decision to chub?"

If the user declines, move on immediately. Don't nag.

What counts as a "meaningful decision":
- Architecture or design choices (database selection, API design, service boundaries)
- Tooling and dependency choices (library A vs B, framework selection)
- Deployment and infrastructure choices (hosting, scaling strategy, CI/CD)
- Process decisions (branching strategy, review process, testing approach)
- Security tradeoffs (auth mechanism, data handling, access control)
- Scope decisions (feature cut, MVP boundary, what to defer)

What does NOT count:
- Routine code changes (renaming a variable, fixing a typo)
- Obvious best practices (adding error handling, following lint rules)
- Temporary debugging choices ("let's try adding a log here")

## Decision Entry Structure

Each decision is appended to a per-project decisions doc in chub. The doc lives at:
```
~/.chub-internal/neuronbox/docs/decisions-<project>/DOC.md
```

If the doc doesn't exist yet, create it with this frontmatter. The `languages` and `versions` fields are required by `chub build` — always include them:

```markdown
---
name: decisions-<project>
description: Decision log for <project> — architecture, tooling, deployment, process, and security decisions with full context and rationale.
metadata:
  languages: "all"
  versions: "<YYYY.M.DD>"
  revision: 1
  updated-on: "<YYYY-MM-DD>"
  source: decision-log-skill
  tags: "decisions,<project>,adr"
---

# Decision Log: <project>

Accumulated decisions with context, rationale, and telemetry.
```

### Entry Format

Append each new decision as a section under the main heading:

```markdown
---

## DEC-<NNN>: <short title>

**Date:** <YYYY-MM-DD>
**Category:** <one of: architecture | tooling | deployment | process | security | scope>
**Tags:** <free-form comma-separated tags>
**Status:** accepted

### Context

<What situation or problem prompted this decision? What were we trying to achieve? Include enough background that someone reading this 6 months later — without access to this conversation — understands the landscape.>

### Alternatives Considered

| Option | Pros | Cons |
|--------|------|------|
| <option A> | ... | ... |
| <option B> | ... | ... |

### Decision

<What was decided and why. Be specific — not "we chose option A" but "we chose per-project decision logs because they mirror the existing chub structure and keep entries focused.">

### Consequences

<What follows from this decision. Structure as:>
- **Easier:** <what this decision simplifies>
- **Harder:** <what this decision makes more difficult or defers>
- **Constraints:** <new constraints or invariants this imposes>

### Telemetry

| Field | Value |
|-------|-------|
| project | <project name> |
| working_dir | <cwd> |
| model | <model ID> |
| files_involved | <comma-separated list of files touched or discussed> |
| tools_used | <tools invoked during this decision> |
| conversation_turns | <approximate turn count> |
| session_duration_est | <rough estimate> |
```

## Numbering

Decision IDs are sequential per project. When appending to an existing doc, read the last `DEC-<NNN>` entry and increment. If the doc is new, start at `DEC-001`.

## Determining the Project

Infer the project from context:
1. If working in a project directory with a CLAUDE.md, use that project's name
2. If the user mentions a specific project/bot (DB, Nook, X, M-Bot), use that
3. If ambiguous, ask: "Which project should I log this under?"

Map common names to chub slugs:
- DB / OpenClaw / Neuron → `openclaw`
- Nook / Letta → `nook`
- X / NanoClaw → `nanoclaw`
- M-Bot / OpenJarvis → `mbot`
- AEGIS → `aegis`

If the project doesn't match any known slug, create a new one using the project's lowercase name.

## After Logging

1. Increment the `revision` number in the doc's frontmatter
2. Update the `updated-on` date
3. Rebuild the chub registry:
   ```bash
   chub build ~/.chub-internal -o ~/.chub-internal/dist
   ```
4. Confirm to the user: "Logged DEC-<NNN> to decisions-<project>: <title>"

## Retrieving Past Decisions

When the user asks about past decisions ("why did we choose X?", "what decisions have we made about Y?"), search chub:
```bash
chub search "decisions <project>"
```
Then read the relevant doc and surface the matching entries.