Todo System Organization & Status Tracking

By Jay Griffin  ·  January 23, 2026
docs
🏷️ Tags:todometaorganizationworkflowfeature-spec

Problem

Currently using todos-as-content-pages pattern (which is great!), but organization and tracking is inconsistent:

Current state:

What works well:

What needs improvement:

Desired Patterns

1. Title Convention: NO "Todo" Prefix

Bad (redundant):

.txt
title: "Todo: Docs Homepage"
title: "Todo: Hide Header Metadata"

Good (descriptive):

.txt
title: "Docs Homepage Routing Decision"
title: "Hide Header Metadata Field"
title: "Metadata Editor Implementation"

Rationale:

2. Status Tracking Field

Add status field to PostMeta for todos:

.ts
// In src/types/post.ts
export interface PostMeta {
  // ... existing fields
  status?: 'open' | 'in-progress' | 'done' | 'blocked' | 'wont-do';
}

Usage in frontmatter:

.json
{
  "title": "Metadata Editor Implementation",
  "slug": "metadata-editor",
  "type": "doc",
  "tags": ["todo", "feature", "metadata"],
  "status": "open"
}

Status meanings:

3. Linking Todos to Work

GitHub Issue style: Issue → Commit → Resolution

Our equivalent:

.json
{
  "title": "Hide Header Metadata Field",
  "slug": "hide-header-metadata",
  "type": "doc",
  "tags": ["todo", "metadata", "components"],
  "status": "done",
  "resolvedBy": "commit-2026-01-25-metadata-controls",
  "relatedCommits": ["commit-2026-01-25-metadata-controls"]
}

Or simpler, just link in the content:

.md
## Resolution

Implemented in [Metadata Controls Commit](/docs/commits/metadata-controls-commit).

Changes:
- Added `hideHeader?: boolean` to PostMeta
- Updated page rendering logic
- Applied to about-me.tsx

4. Todo Overview Page

Create /todos page (or filtered view on homepage) showing:

Open Todos:

In Progress:

Completed:

Blocked:

Implementation: MVP

Step 1: Add Status Field to Type

Update src/types/post.ts:

.ts
export interface PostMeta {
  title: string;
  slug: string;
  date: string;
  author?: string | string[];
  authorshipNote?: string;
  description?: string;
  type: 'post' | 'doc' | 'doc:commit';
  tags?: string[];
  status?: 'open' | 'in-progress' | 'done' | 'blocked' | 'wont-do'; // NEW
  // ... other fields
}

Step 2: Update Existing Todos

Add status: 'open' to all current todos:

Step 3: Visual Indicators in Navigator

Update Navigator to show status badges:

.ts
// In Navigator component
const statusIcons = {
  open: '🔲',
  'in-progress': '🔄',
  done: '✅',
  blocked: '🚧',
  'wont-do': '❌',
};

{posts.map(post => (
  <div key={post.slug}>
    {post.tags?.includes('todo') && post.status && (
      <span>{statusIcons[post.status]} </span>
    )}
    <Link href={post.route}>{post.title}</Link>
  </div>
))}

Step 4: Filter Todos by Status

Add filtering to Navigator or create dedicated /todos view:

.ts
const todos = posts.filter(p => p.tags?.includes('todo'));
const openTodos = todos.filter(t => t.status === 'open');
const inProgressTodos = todos.filter(t => t.status === 'in-progress');
const doneTodos = todos.filter(t => t.status === 'done');

Implementation: Future Enhancements

Auto-link Todos to Commits

When creating a commit summary doc, check for related todos and auto-update their status:

.ts
// In commit doc frontmatter
{
  "title": "Metadata Controls Implementation",
  "type": "doc:commit",
  "resolves": ["hide-header-metadata"], // Slug of todo(s) resolved
}

Script to auto-update todos:

.sh
# Find commit docs with "resolves" field
# Update corresponding todo status to "done"
# Add "resolvedBy" link to todo

Todo Board View

Create Kanban-style board at /todos/board:

.txt
| Open          | In Progress       | Done              |
|---------------|-------------------|-------------------|
| Metadata Edit | Private Content   | Hide Header       |
| Search/Filter |                   | Authorship Update |
| Docs Homepage |                   |                   |

Drag-and-drop to change status (updates frontmatter).

Priority Field

Add priority to PostMeta:

.ts
priority?: 'low' | 'medium' | 'high' | 'critical';

Sort todos by priority in overview.

Due Dates

Add dueDate field:

.ts
dueDate?: string; // ISO 8601 format

Show overdue todos in red, upcoming in yellow.

Todo Templates

Create templates for common todo types:

Feature Spec Template:

.md
## Problem
[What needs to be solved]

## Proposed Solution
[How to solve it]

## Implementation Steps
1. Step one
2. Step two

## Files to Modify
- `src/file1.ts`
- `src/file2.ts`

## Related
- [Related Todo](#)
- [Related Commit](#)

Bug Fix Template:

.md
## Bug Description
[What's broken]

## Expected Behavior
[What should happen]

## Actual Behavior
[What currently happens]

## Steps to Reproduce
1. Step one
2. Step two

## Proposed Fix
[How to fix it]

Archive Completed Todos

Option 1: Move to content/archive/todos/ Option 2: Keep in place but filter by status Option 3: Add archived: true field

Preference: Option 2 (keep everything, filter by status). Completed todos serve as documentation.

Integration with Metadata Editor

When the metadata editor exists, bulk operations on todos become trivial:

Bulk status update:

Bulk cleanup:

Consistency check:

Current Naming Cleanup Needed

These todos need title updates:

Actually, reviewing existing todos - the titles are already good! They don't have "Todo:" prefix, they're descriptive. The filenames have "todo-" prefix for clarity, which is fine.

Pattern to maintain:

Examples of Good Todo Metadata

Feature Request:

.json
{
  "title": "Metadata Editor with AI Assistance",
  "slug": "metadata-editor-feature",
  "type": "doc",
  "tags": ["todo", "feature", "metadata", "ai"],
  "status": "open",
  "priority": "high",
  "description": "Build AI-powered metadata editor for bulk operations on content"
}

Bug Fix:

.json
{
  "title": "CodeBlock Formatting in Dark Mode",
  "slug": "codeblock-dark-mode-bug",
  "type": "doc",
  "tags": ["todo", "bug", "styling", "codeblock"],
  "status": "in-progress",
  "priority": "medium"
}

Research/Decision:

.json
{
  "title": "Docs Homepage Routing Strategy",
  "slug": "docs-routing-decision",
  "type": "doc",
  "tags": ["todo", "routing", "architecture", "decision"],
  "status": "open",
  "priority": "medium",
  "description": "Decide between dedicated /docs page, unified homepage, or redirect pattern"
}

Completed:

.json
{
  "title": "Hide Header Metadata Field",
  "slug": "hide-header-metadata",
  "type": "doc",
  "tags": ["todo", "metadata", "components"],
  "status": "done",
  "resolvedBy": "commit-2026-01-25-metadata-controls",
  "description": "Add optional hideHeader field to PostMeta for component control"
}

Why This Matters

A well-organized todo system means:

  1. Never lose track of work - Everything documented, statusable, searchable
  2. Clear priorities - Know what to work on next
  3. Historical record - See what was planned, what shipped, what was abandoned
  4. Onboarding - Future employer/collaborator can see your thought process
  5. Validated by metadata editor - Bulk operations prove the system's power

The todo system isn't just task tracking—it's project memory as queryable data.

Timeline

Now (5 minutes):

Soon (1 hour):

Later (2-3 hours):

Eventually: