nudge-space/docs/concept_v0.1.md

---
title: "Nudge Space — Concept v0.1"
type: concept
status: draft
repo: nudge-space
domain: infotech
created: "2026-10-04"
updated: "2026-10-04"
---

# Nudge Space — Concept v0.1

Nudge Space is a parking lot for the ecosystem. A participant encounters
something relevant, and the encounter is not worth a task. The thought is
also too interesting to drop on the floor. It goes into peripheral view:
kept, searchable, and able to show its face again if it keeps coming back.

This is the earliest layer of value and product discovery. The material is
semi-structured on purpose. It is a collection of hunches, not a product
backlog and not a design.

A **discovery topic** in this document is a theme that emerges from many
nudges, the way a word cloud grows. That is a different thing from a State
Hub topic, which is the registration bucket this repository sits in.

## The situation it answers

Work in this estate is coordinated by work records: intakes, workplans,
tasks, decisions. That backbone is for things someone has decided to carry.
The path into it is easy to overuse. A sharp remark in a review, a repeated
irritation, a half-seen product shape, a tool that might matter next year:
each of these can be written up as a task in a minute, and each such task
competes with the work that already has the floor.

The other failure is silence. The same hunch appears in three repositories
over a month, and nobody can see that, because each encounter was forgotten
at the end of the session.

The parking-lot rule from agile meetings is the remedy. The thought is
acknowledged, written where it can be found, and left alone. Attention
returns to the agenda. Later, if the thought is still there, or if it has
accumulated neighbours, someone can choose to pick it up.

## What a nudge is

A nudge is a short note of an encounter.

It has:

- something that was noticed
- where it was encountered
- when
- enough words that a later reader can recognise it
- optional tags, which are the seeds of the heatmap

It has no status, no owner, no estimate, and no acceptance criteria. It is
not finished or cancelled. It sits.

A nudge is earlier than an intake. An intake, in the fleet work-record
standard, is a spark someone has decided should enter coordination. A nudge
is the spark before that decision. The kind registry of work records stays
closed. A note with no lifecycle is already outside that registry: the
standard says so for `RISK-N-*` notes, and the same line is drawn here.

Promotion, when it happens, happens somewhere else. A person or an agent
creates an intake or a workplan in the repository that should own the work,
and may then add a `promoted` pointer on the nudge. The nudge file stays in
place, so the periphery still shows that the thought existed and where the
work went.

## Where nudges live

A repository connects to Nudge Space by keeping its nudges in a top-level
folder named `nudges/`.

The folder is the whole integration. There is no registration call per
nudge, and participants do not copy their notes into this repository. The
note stays next to the work where it was encountered, and it is published
the same way the rest of that repository is published: a commit on Forgejo.

This repository follows the same convention for hunches encountered while
working on Nudge Space itself. Its `nudges/` folder is a participant folder.
The index this repository will eventually build is a projection of many such
folders, including its own.

### File shape

One nudge is one Markdown file.

```text
nudges/YYYYMMDD-short-slug.md
```

The date is the day it was first written. The slug is stable. Renaming is a
later problem for the reader; until then the path is the identity, together
with the repository that holds it.

```yaml
---
title: A few words naming the hunch
noticed: 2026-10-04
origin: repo, conversation, document, or url — specific enough to find again
tags: [kebab-case, another-theme]
---

What was noticed. A few sentences of the original thought are enough.

Why it is parked. One or two sentences on why it should stay in the periphery.
```

Optional fields, used when they are true:

| Field | Meaning |
|---|---|
| `recurrence` | Whole number. Bump it when the same hunch shows up again. Absent means once. |
| `see_also` | Paths or URLs that belong to the same encounter. |
| `promoted` | Id of a work record created elsewhere, after a deliberate promotion. |

The body can be rough. Write the thought in the words it arrived in. Do not
add a task list, a design, an estimate, or an owner. Those are the marks of
work, and work belongs in a work record.

A future reader skips, and does not index as nudges:

- `README.md`
- names that start with `.` or `_`
- anything outside `nudges/`

## How this repository reads them

The intended reader is Nudge Space, fetching participant folders through
Forgejo.

The shape of that read:

1. The set of repositories is the set this estate already publishes on
   Forgejo. The remote form already used here is
   `forgejo-remote:coulomb/<repo>`.
2. The reader fetches a repository read-only and takes `nudges/**/*.md` at a
   commit.
3. It does not commit back into participant repositories.
4. It uses whatever Forgejo read access the estate already has. This concept
   opens no new credential lane.
5. A collected nudge is identified by repository plus path. Frontmatter
   enriches that identity. It does not replace it.

Search and exploration sit on top of that collection: words, tags, origin
repository, and date. Opening a tag shows the files that fed it, each still
pointing at its home repository.

v0.1 does not build that reader. It fixes the place the notes live and the
shape they have, so a later reader has an honest corpus.

## The heatmap

Over time the collection develops a topic heatmap, close to a word cloud.

Tokens come from `tags`, from `title`, and from phrases that repeat in the
bodies. A token gains weight when more nudges carry it, when they come from
more than one repository, and when they recur or arrive recently. The exact
weighting waits until there is a body of nudges to look at. Choosing a
formula against an empty collection would be ceremony.

The heatmap is a perception aid. It answers "what keeps coming back?" It
does not sort a backlog, assign an owner, or create a task. A bright topic
is a reason to look. Looking is optional.

## Where this sits in discovery

Earliest first:

1. **Nudge.** Noticed, parked, still peripheral. This repository.
2. **Intake.** Someone decides the spark should enter coordination. The
   owning repository.
3. **Workplan and tasks.** The spark has a body of work. The owning
   repository.
4. **Product, tool, or canon.** The work has a durable home.

Nudge Space owns step 1. Steps 2–4 stay in the repositories that take the
work up. State Hub remains the read model for those work records. Nudges are
not projected into it as tasks.

## What v0.1 establishes

- This intent and concept.
- The `nudges/` convention and the file shape above.
- Registration of the repository with State Hub, so the place has an address
  in the estate.

## What stays undesigned until someone promotes it

These are named so they are not forgotten. They are not tasks.

- The Forgejo fetch and the index.
- The search and exploration space.
- The weighting of the heatmap.
- Any view that spans private repositories beyond the Forgejo access that
  already exists.

A recurring theme in the corpus is the evidence that one of these, or any
other hunch, might deserve an intake. The evidence is the recurrence. The
decision to promote stays explicit, and it is made outside this folder.