Skip to content

finos/morphir-scala / .claude/skills/intent

intent

Verified

Manages intent — features, enhancements, bugs and the reasoning behind them — recorded as prose in the knowledge base with a lifecycle. Use when capturing new work, moving work through backlog, refinement or implementation, releasing or cancelling work, or asking what is pending, in flight, or no longer valid.

FileKindSize
SKILL.mdskill md5.8 KB
---
name: intent
description: "Manages intent — features, enhancements, bugs and the reasoning behind them — recorded as prose in the knowledge base with a lifecycle. Use when capturing new work, moving work through backlog, refinement or implementation, releasing or cancelling work, or asking what is pending, in flight, or no longer valid."
allowed-tools: Bash(.claude/skills/kb/kb *), Bash(cat *), Bash(ls *), Bash(git *), Bash(gh *), Read, Edit, Write
metadata:
  version: 0.1.0
---

# intent — Managing What the Project Means to Do

This skill is the process; the mechanics live in the `kb` skill. Every command below is `.claude/skills/kb/kb intent
…`. There is no separate implementation — see [decision 0002](../../../kb/bundles/morphir/morphir-scala/decisions/0002-intent-tooling-lives-in-the-kb-skill.md)
for why, and do not try to split them without reading it first.

```bash
.claude/skills/kb/kb intent list --open
```

## The one distinction that matters

**Intent** is future-tense and has a lifecycle — what the project means to do. **Capability** is present-tense and is
simply either true or stale — what the system does today. They are different documents in different bundles, and
conflating them is what makes knowledge bases rot.

Releasing is where they meet: marking an Intent Released **requires** linking the Capability it produced. That single
obligation is what stops the knowledge base falling behind the code.

Full glossary: [kb/CONTEXT.md](../../../kb/CONTEXT.md).

## Lifecycle

```
Backlog ──▶ Refinement ──▶ InProgress ──▶ Released
   └──────────┴─────────────┴──────────▶ Cancelled / Superseded
```

| State | Means | Owes |
| ----- | ----- | ---- |
| `Backlog` | Accepted as real work, not yet specified | — |
| `Refinement` | Being specified; the design is not settled | — |
| `InProgress` | Design settled, actively being built | — |
| `Released` | Shipped | A Capability link, for user-visible kinds |
| `Cancelled` | Decided against | A reason |
| `Superseded` | Replaced by another Intent | A successor |

Transitions are **not** policed — work genuinely jumps stages, and a one-line fix may go Backlog straight to
Released. What is enforced is what a record owes *wherever it currently sits*.

**Deprecated is not a state.** You deprecate a shipped Capability, not a backlog item. Retiring something is *new*
Intent, of `kind: deprecation`, followed later by one of `kind: removal`.

## Kinds

User-visible — these appear in release notes:

`feature` · `bug` · `performance` · `security` · `deprecation` · `removal`

Internal — these do not:

`refactor` · `docs` · `test` · `build` · `spike`

`breaking: true` is separate from kind, because a feature *or* a bug fix can break compatibility. It is what drives a
major bump.

Only user-visible kinds must link a Capability on release. Internal work often has nothing for the knowledge base to
learn, and inventing a document for "added three labels" is the noise this design avoids.

## Working with it

**Capture.** GitHub Issues is the inbox — anyone may file there. An issue becomes Intent when a maintainer decides it
is real work worth durable prose. Most issues never do.

```bash
.claude/skills/kb/kb intent new --title "…" --description "…" --kind feature --issue 1234
```

Then write the **Problem** section. Resist describing a solution there — the Feature Request template's Job Story
form ("When *[trigger]*, I want to *[goal]*, so I can *[outcome]*") is a good discipline.

**Progress.**

```bash
.claude/skills/kb/kb intent refine 0007
```

```bash
.claude/skills/kb/kb intent start 0007
```

**Finish.** Each verb demands what its state owes, at the moment you have the answer:

```bash
.claude/skills/kb/kb intent release 0007 --capability morphir/morphir-scala:/wasm-linking.md --artifact pkg:maven/org.finos.morphir/morphir-langkit@0.4.0
```

```bash
.claude/skills/kb/kb intent cancel 0007 --reason "…"
```

```bash
.claude/skills/kb/kb intent supersede 0007 --by 0012
```

**After any change**, regenerate the index and the database:

```bash
.claude/skills/kb/kb refresh
```

## Asking questions

```bash
.claude/skills/kb/kb intent list --open
```

```bash
.claude/skills/kb/kb intent list --user-visible --state Released
```

Anything more involved goes through SQL against the `v_intent` view:

```bash
.claude/skills/kb/kb query --sql "SELECT state, kind, count(*) FROM v_intent GROUP BY 1,2 ORDER BY 3 DESC"
```

## Keeping it honest

```bash
.claude/skills/kb/kb intent check
```

Errors are unmet obligations — a Released record with no Capability, a Cancelled one with no reason, a `superseded_by`
naming nothing. Warnings are staleness: an Intent sitting in Refinement or InProgress past the bundle's
`stale_after_days` is the honest signal that nobody is working on it. Move it on, or move it back to Backlog and say
so.

Backlog is deliberately never stale. A backlog is *meant* to sit.

## Portability

Nothing is hardcoded. The intent bundle is the one whose `index.md` frontmatter carries `intent: true`, and its
settings live there too:

```yaml
intent: true
system: pkg:maven/org.finos.morphir/morphir-core
capability_bundle: morphir/morphir-scala
stale_after_days: 60
```

`system` and released `artifacts` are [Package URLs](https://github.com/package-url/purl-spec) — a global vocabulary,
so the same skill works in a Python or npm repository unchanged. Capability links use `bundle-label:/path.md`
instead, because a Capability is a document in this knowledge base, not a registry-backed package.
[decision 0003](../../../kb/bundles/morphir/morphir-scala/decisions/0003-two-identifier-schemes-for-intent.md) records why both exist.

In a repository with no intent bundle yet:

```bash
.claude/skills/kb/kb intent init --system pkg:pypi/example --capability-bundle example
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall