Ideas, problems and thoughts

How ideas, problems and thoughts are filed as ordinary pages under three parent pages, optionally labelled with a project, and shown on each project's homepage.

A design for filing three kinds of notes (ideas, problems and thoughts), making them easy to create and read, and showing them on each project's homepage. A note can belong to a project, or to none. This is a plan to review, not built yet.

What I want

  • Three kinds of page: ideas (features I'd like), problems (things that are broken or annoying) and thoughts (everything else I think about while working).
  • They get filed in the right place without me thinking about it.
  • They're easy to make. I say "file an idea" and it exists.
  • They're easy to read. Each kind has a page that lists all of it.
  • They appear on a project's homepage, such as /projects/jaygriff-v4.
  • Any of them can have no project and stand alone.

What I mean by "parent page"

Nothing in this design is a folder on disk or a route in src/app. Every note, and every list of notes, is an ordinary goatboat content record, like any other page on the site.

A content record can have a parent record, and its URL path is its parent's path plus its own slug. So the note at /ideas/heading-sizes-from-goatboat has the record at /ideas as its parent page.

recordslugparentpath
the ideas pageideasnone/ideas
a noteheading-sizes-from-goatboatthe ideas page/ideas/heading-sizes-from-goatboat

The site already renders any record at its path through the catch-all route, and lists a page's children at the bottom of it. So /ideas is just a normal page that happens to list its children.

The one idea

Every note has two separate facts about it:

FactWhat it isValues
KindWhich parent page the note sits underthe page at /ideas, /problems or /thoughts
ProjectA field on the record (projectId), which is optionaljaygriff-v4, goatboat, or nothing

The kind is where the note sits in the tree. The project is a label on the record. Because they're independent, a note about nothing in particular just sits under its kind's parent page with no label, and a project's homepage only has to ask "which notes carry my label?"

The other design I considered put a set of parent pages inside each project (/projects/jaygriff-v4/ideas/...). It needs three extra records for every project, and a note with no project has nowhere to go. This one needs three parent pages in total.

A walk-through

  1. I tell the agent: "file an idea for jaygriff-v4: change heading sizes from goatboat".
  2. The agent proposes a page at /ideas/heading-sizes-from-goatboat. It has a title, a one-line description, my words as the body, the project jaygriff-v4, and the status published.
  3. I read the proposal and approve it. Approving is the only step.
  4. The page is live at its URL. It shows in the list at /ideas, and on /projects/jaygriff-v4 under Ideas.
  5. If I say "file a thought: ..." with no project, it goes to /thoughts/.... It shows in the list at /thoughts and on no project's homepage.

What already works

  • Every page has an optional project (content.projectId). The agent tool for editing a page's metadata can already set it by project slug.
  • Any page at any path is rendered by the site's catch-all route, and it lists its child pages at the bottom. So a page such as /ideas automatically lists everything under it.
  • Proposals, approval, and the create and publish ops.

What changes, piece by piece

1. Three parent pages (one time)

Create /ideas, /problems and /thoughts as ordinary published pages, each with a short description of what belongs there. They are content records, not code. I'll create them with one proposal containing three create changes. They need to exist because a page can only be created under a parent that exists. Each lists every note of its kind, from every project.

I checked that none of these three paths exist yet.

2. The agent's create tool takes a project and a status

create_page (and the create change inside propose_changes) gets two optional inputs:

  • project: a project slug. The tool looks the id up and sends it as projectId, the same way the metadata tool already does.
  • status: published or draft. The default becomes published, so approving the proposal puts the page live. draft is for when I ask for one.

Goatboat's content creation already accepts both fields and sets the publish date itself, so nothing changes in the database or in goatboat's own code. Only the agent tool changes, plus the tool description, which currently tells agents to publish only when asked.

3. A project filter on the content API

GET /api/content currently filters by type, tag and status. It gets ?project=<slug>, which returns only content with that project and combines with the other filters. Paging totals respect it. An unknown slug returns an empty list. This is a small change to the content query, the route that reads the parameter, and tests.

4. The project page on the site

A new dynamic route, src/app/projects/[slug]/page.tsx, with a CSS module, serves every project. This is the only new code route.

  • It finds the project by slug and returns a 404 if there isn't one or it isn't visible.
  • The header shows the title, tagline, description, repo, demo and video links, and tags.
  • It asks goatboat for all content with this project, then groups it by which parent page each record sits under, using the first part of its path: /ideas as Ideas, /problems as Problems, /thoughts as Thoughts, and anything else (my docs and tests) as Docs and other pages.
  • Each group is a list of title, description and date, newest first. A group with nothing in it is hidden.
  • The first version reuses the existing feed list component.
  • The route isn't synced to goatboat, so it supplies its own title and its own breadcrumbs, "Projects › the project's name".
  • The site client's content query gets the new project option.

This route handles /projects/<slug> before the catch-all would. No goatboat page lives at those paths, so nothing is hidden.

What stays the same

  • The database schema. There's no migration.
  • The routes sync, the GitHub Action and the pre-commit hook.
  • My existing docs and tests and the project assignments I already approved. They show under "Docs and other pages".

Edge cases

  • No project: it sits under its kind's parent page and shows in that kind's list only.
  • Wrong kind: move it to the other parent page. The old URL redirects to the new one.
  • Change or clear the project: one metadata change with the project slug, or null.
  • A project is deleted: its notes stay, lose the label, and become standalone notes under their parent pages.
  • Drafts: they show only in local dev, as everywhere else.
  • Same title twice: slugs must be unique among a parent page's children, so a duplicate is refused when approving. I'd add a distinguishing word to the slug.
  • Many notes: the first version asks for up to 200 per project. Paging comes later if it's needed.

Build order

Each step works on its own.

  1. Agent create tool takes project and status. Done when I can propose a published /ideas/test note with a project.
  2. The three parent pages. Done when /ideas, /problems and /thoughts render.
  3. The content API project filter, with tests.
  4. The project page. Done when /projects/jaygriff-v4 shows its notes grouped by kind.
  5. File the first real notes.

Not doing

  • No deferred or done state, no priority, no issue numbers.
  • No GitHub issue field. If I want one later, it's a single optional column, a separate change.
  • No per-project parent pages.

Questions

  • Are Ideas, Problems and Thoughts the right names?
  • Should the three parent pages be linked from somewhere, such as the Projects page, or reached by URL only?