Manage Johnny.Decimal systems with AI-assisted inbox processing, classification, JDex maintenance, and system setup. Supports single and multi-system (SYS.AC.ID) configurations.

GitHub stars
7

Install

/plugin install jd@jd-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ngerakines/jd.

Contents

Discovered from source

Skills 6

Johnny.Decimal Inbox Processor

This skill processes items in Johnny.Decimal 00.01 Inbox folders — reading each item, classifying it against the system's JDex and folder structure, and moving it to the correct ID location. When classification is ambiguous, it asks the user to decide. It also extracts tasks, updates the JDex, and logs every action.

Before processing, read references/jd-system-rules.md for the structural conventions that govern all classification decisions.


1. Orientation: Discover the JD Environment

Before touching any files, build a mental map of the user's JD setup.

1.1 Locate the JD Root

The JD root folder is wherever the user's systems live. Common locations:

  • ~/Library/Mobile Documents/com~apple~CloudDocs/JD/ (iCloud Drive)
  • ~/Documents/JD/
  • ~/JD/
  • A project-specific folder the user designates

If you don't know the root, ask the user. If the user says "process my inbox" without further context, check the most common locations above. If you find exactly one, confirm it. If you find multiple or none, ask.

1.2 Identify Systems

List the top-level folders under the JD root. Each folder whose name matches the pattern [A-Z][0-9][0-9] * is a JD system (e.g., P10 Personal, W20 Work, C40 Citywide).

If the user has a single system (no SYS prefix), that's fine — treat the entire JD root as one system.

1.3 Load Each System's JDex

For every system you'll process, read the JDex file at:

SYS/00-09 */00 */00.00 *JDex*

The JDex is the authoritative index of every area, category, and ID. It is your primary classification reference. If the JDex is missing or empty for a system, fall back to reading the folder structure directly — but flag this to the user as something that should be fixed.

1.4 Snapshot the Folder Structure

For each system, list the area folders, category folders, and ID folders to depth 3. This gives you the physical layout to validate against the JDex and to discover any folders not yet in the index.


2. Inbox Discovery

2.1 Locate Inboxes

Each system's inbox lives at:

SYS/00-09 */00 */00.01 Inbox/

List the contents of every inbox you find. If the user asked to process a specific system's inbox (e.g., "process my P10 inbox"), limit to that one.

2.2 Assess the Inbox

For each inbox, report to the user:

  • Item count: How many files/folders are in the inbox
  • Item types: File types present (.md, .pdf, .jpg, .txt, etc.)
  • Date range: Earliest and latest date-prefixed items

If the inbox is empty, say so and move on. If it contains more than ~20 items, suggest processing in batches and ask the user how many to tackle.


3. Process Each Item

Work through inbox items one at a time (or in logical groups if items are clearly related, like a note and its accompanying photo). For each item:

3.1 Read and Understand the Item

  • Text files (.md, .txt): Read the full content.
  • PDFs: Read if possible; if not readable, use the filename and any available metadata.
  • Images (.jpg, .png): Describe what you see. If it's a photo of a document, extract what you can.
  • Other files: Use the filename, extension, and file size to infer purpose.

Summarize what the item is about in one sentence. This is your "item summary" and is used in the processing log.

3.2 Classify the Item

Classification follows a strict decision tree. At each level, you're choosing from a bounded set (≤10 options). This is where the JDex is critical.

Read references/classification-heuristics.md for detailed guidance on ambiguous cases.

Step 1 — Which system? (Multi-system setups only)

If the user has multiple systems, determine which system the item belongs to. Signals include:

  • Explicit system references in the content ("Citywide," "work," "personal")
  • Content domain (tax docs → personal, buyer meeting notes → work)
  • Filename patterns or prefixes the user may use

If ambiguous between systems, ask the user.

Step 2 — Which area?

Read the area list from the JDex. Choose the area whose description best matches the item's content. Areas are broad domains (10-19 Home & property, 30-39 Money & legal, etc.).

If no area fits, this may indicate:

  • The item belongs in a different system
  • The system needs a new area (rare — flag for user decision, do not create)
  • The item is miscategorized in the user's mind (ask)

Step 3 — Which category?

Within the chosen area, pick the category. Categories are collections of similar things. This is "where you work" — the most important classification decision.

Step 4 — Which ID?

Within the category, determine the specific ID folder:

  • Existing ID matches: The item clearly belongs in an existing ID folder. Use it.
  • +SUB match: If the category uses +SUB extensions (e.g., 11.01+REDD), match the item to the correct sub-entry.
  • New ID needed: If no existing ID fits, you may need to create one. See §3.4.

3.3 Confidence Assessment

After classification, assess your confidence:

  • High confidence (clear match, unambiguous): Proceed to filing.
  • Medium confidence (reasonable match, but another location is plausible): State your recommendation and the alternative, then ask the user to confirm.
  • Low confidence (genuinely unclear): Present the top 2–3 candidate locations with brief reasoning, and ask the user to choose.

The threshold: if you'd bet money on the classification, it's high confidence. If you'd want a second opinion, it's medium. If you're guessing, it's low.

When asking the user, be specific. Not "where should this go?" but rather:

This looks like a health insurance claim. I'd file it at P10.34.01 (Health insurance). Does that sound right, or does it belong somewhere else?

3.4 Creating New IDs

If an item needs a new ID (no existing ID in the category fits), follow these rules strictly:

  1. Never create a new area or category without explicit user approval. These are structural decisions that affect the whole system. Flag the need and ask.
  2. New IDs within an existing category are lower-stakes. You may propose a new ID, but always confirm with the user before creating it.
  3. Determine the next sequential ID number. Look at existing IDs in the category. If the highest is 15.23, the next is 15.24. If the category uses standard zeros (.00–.09 reserved), the first content ID is .10 or the next available number above .09.
  4. Name the new ID clearly. Follow the pattern of existing IDs in the category. JD ID folder names are: AC.ID Description (e.g., 15.24 Trip to Portland).
  5. After creating the folder, update the JDex with the new entry.

For +SUB entries, the process is similar but uses the +NNNN or +CODE pattern established in that category.

3.5 Filing the Item

Once the destination is confirmed:

  1. Rename the file with a date prefix if it doesn't already have one. Format: YYYY-MM-DD Description.ext. Use today's date if the item has no inherent date. Use the item's date if it does (e.g., a receipt dated 2026-01-15).

  2. Move the file from the inbox to the destination ID folder.

  3. If the item contains actionable tasks, extract them. See §4.

  4. If the item is both a record and a task source, file the record AND extract the tasks. Don't choose one or the other.

3.6 Items That Don't Belong

Some inbox items are:

  • Stale or irrelevant: Old notes that are no longer needed. Confirm with the user, then move to 00.09 Archive if that folder exists, or delete if the user prefers.
  • Duplicates: The same content already exists at the destination. Flag to the user and offer to delete the inbox copy.
  • Cross-system references: The item belongs in System A but was captured in System B's inbox. Move it to System A's inbox (or directly to the correct ID if classification is clear), and note the cross-reference.

4. Task Extraction

Many inbox items contain embedded tasks — things the user needs to do. When you identify a task, extract it.

4.1 Identifying Tasks

Look for:

  • Explicit action items ("need to send pricing," "follow up with Jordan")
  • Deadlines ("by end of week," "before March 8")
  • Commitments ("promised to deliver," "agreed to check on")
  • Questions that need answers ("check with warehouse," "ask about delivery")

4.2 Task Format

Append extracted tasks to the system's task file at:

SYS/00-09 */00 */00.02 Tasks*

Each task should include:

- [ ] [Task description]
      → [JD reference: AC.ID or AC.ID+SUB] | Deadline: [date or "none"] | Source: [inbox item filename]

If the task file doesn't exist, create it. If the task file uses a different format, match the existing format.

4.3 Task Context

When possible, add context from the JD system to the task:

  • Reference relevant IDs (e.g., "Pricing info in 31.03")
  • Note related contacts or accounts
  • Link to the filed record

5. Logging

After processing each item, append a log entry to:

SYS/00-09 */00 */00.03 Processing log.md

If this file doesn't exist, create it.

Log Entry Format

### YYYY-MM-DD HH:MM — Inbox Processing

| Item | Action | Destination | Notes |
|------|--------|-------------|-------|
| `filename.ext` | Filed | `AC.ID Description` | One-line summary |
| `filename2.md` | Filed + Task | `AC.ID+SUB` | Task added to 00.02 |
| `filename3.pdf` | Needs review | `00.04 Needs review` | Ambiguous; user asked to decide later |
| `filename4.txt` | Archived | `00.09 Archive` | Stale item, confirmed by user |

**Items processed**: N
**Tasks extracted**: N
**Needs review**: N
**New IDs created**: [list, or "none"]

6. JDex Maintenance

After all items are processed, verify the JDex:

  1. New entries: If any new IDs or +SUB entries were created during processing, confirm they've been added to the JDex.
  2. Orphan check (optional, suggest to user): Compare the JDex against the actual folder structure. Flag any folder that exists but isn't in the JDex, and any JDex entry whose folder doesn't exist.

7. Multi-System Processing

When the user says "process my inboxes" (plural) or doesn't specify a system:

  1. List all systems with non-empty inboxes.
  2. Report the item count per system.
  3. Ask whether to process all of them or just specific ones.
  4. Process each system's inbox in sequence. Keep system context separate — don't confuse P10's JDex with W20's categories.
  5. At the end, give a combined summary across all systems.

8. Interaction Principles

8.1 When to Ask vs. When to Act

  • Act without asking: Filing an item to a clearly matching existing ID with proper date-prefix naming. This is routine and unambiguous.
  • State and confirm in batch: When processing multiple items, you can propose a batch of filings and let the user approve them all at once rather than one at a time. Present a table: item → proposed destination.
  • Ask before acting: Creating new IDs, creating new +SUB entries, archiving or deleting items, moving items between systems, any classification with medium or low confidence.
  • Always ask: Creating new categories or areas. These are structural changes.

8.2 Batch Processing Mode

For inboxes with many items, offer batch mode:

  1. Read all items.
  2. Classify each one.
  3. Present a table of proposed actions.
  4. Let the user approve, modify, or flag specific items.
  5. Execute all approved actions.
  6. Handle flagged items individually.

This is faster than one-at-a-time for large inboxes while still giving the user control.

8.3 Learning from User Decisions

When the user corrects a classification or makes a non-obvious filing decision, note the reasoning. This helps you classify similar items in the future within the same session. For example, if the user says "actually, I keep all Northside stuff in 31.02, not by account," apply that pattern to subsequent Northside items.


9. Error Handling

  • JDex missing: Warn the user. Offer to generate one from the folder structure. Process using folders as the reference, but note that a JDex should be created.
  • Inbox folder missing: A system without 00.01 Inbox has no inbox to process. Note this and move on.
  • Unreadable files: If a file can't be read (binary, corrupted, encrypted), log it, skip it, and tell the user.
  • Filesystem errors: If a move fails (permissions, path issues), report the error, skip the item, and continue with the rest.
  • JDex/folder mismatch: If the JDex says an ID exists but the folder doesn't (or vice versa), flag the inconsistency. Don't silently create or delete anything to "fix" it — the user decides.

10. Post-Processing Summary

After completing all inbox processing, present a summary:

Inbox processing complete.

[System name]: [N] items processed
  → [N] filed to existing IDs
  → [N] tasks extracted to 00.02
  → [N] new IDs created: [list]
  → [N] items need review (in 00.04)
  → [N] archived

[Repeat for each system processed]

JDex status: [up to date / N entries added / needs audit]

If any items were moved to "needs review," remind the user they're waiting.


Quick Reference: File Naming Convention

All files in JD ID folders use date-prefix naming:

YYYY-MM-DD Description.ext
  • Use the item's inherent date when available (document date, receipt date, meeting date).
  • Use the capture/creation date if no inherent date exists.
  • Use today's date as a last resort.
  • Keep descriptions short but specific. Match the style of existing files in the same folder.
  • No special characters in filenames beyond hyphens and spaces.

Quick Reference: Standard Zeros

These reserved IDs exist (or may exist) in each category:

IDPurpose
.00Category JDex / index
.01Inbox
.02Tasks / action items
.03Templates (or processing log in system 00)
.04Links / quick reference (or needs-review in system 00)
.08Someday / parking lot
.09Archive

Not all systems use all standard zeros. Check what actually exists.

Johnny.Decimal JDex Audit

This skill compares a system's JDex (the authoritative index) against the actual folder structure on disk, identifying mismatches and suggesting fixes.


1. Locate the System

1.1 Find the JD Root

Check common locations:

  • ~/Library/Mobile Documents/com~apple~CloudDocs/JD/ (iCloud Drive)
  • ~/Documents/JD/
  • ~/JD/

If the user specifies a system code (e.g., "audit my P10 system"), target that specific system. Otherwise, list all available systems and ask which to audit.

1.2 Load the JDex

Read the JDex file at:

SYS/00-09 */00 */00.00 *JDex*

Parse it into a structured list of areas, categories, and IDs. Each entry should capture:

  • The AC.ID (or SYS.AC.ID) address
  • The description/name
  • Any +SUB entries

1.3 Snapshot the Filesystem

List all folders to depth 3 under the system root. Parse folder names to extract AC.ID addresses, area ranges, and category numbers.


2. Compare JDex vs. Filesystem

Run three checks:

2.1 Orphaned JDex Entries

JDex entries that have no corresponding folder on disk.

These indicate either:

  • A folder was deleted without updating the JDex
  • A planned ID that was never created
  • A typo in the JDex entry

2.2 Undocumented Folders

Folders on disk that have no corresponding JDex entry.

These indicate either:

  • A folder was created without updating the JDex
  • The JDex fell out of sync during manual organization
  • A folder created by another tool or process

2.3 Name Mismatches

JDex entries whose description doesn't match the folder name, or folders whose name doesn't follow the expected AC.ID Description format.


3. Check +SUB Indexes

For categories that use +SUB extensions:

3.1 Locate Index Files

+SUB categories typically have an index file (e.g., 51.01 Open-source project index.md). Find these by looking for files matching *.md at the category or ID level that contain +SUB listings.

3.2 Compare Index vs. Folders

  • List all +NNNN or +CODE folders within the ID
  • Compare against the index file entries
  • Flag missing or extra entries

4. Report Findings

Present a clear audit report to the user:

Report Format

## JDex Audit: [System name]

**Audit date:** YYYY-MM-DD
**JDex location:** [path]
**System root:** [path]

### Summary

| Check | Count |
|-------|-------|
| JDex entries | N |
| Filesystem folders | N |
| Orphaned JDex entries | N |
| Undocumented folders | N |
| Name mismatches | N |
| +SUB index issues | N |

### Orphaned JDex Entries (in JDex but no folder)

| AC.ID | Description | Suggested Action |
|-------|-------------|-----------------|
| 11.05 | Home improvement | Create folder or remove from JDex |

### Undocumented Folders (folder exists but not in JDex)

| Folder | Path | Suggested Action |
|--------|------|-----------------|
| 11.08 Garage storage | 10-19/11/11.08 | Add to JDex |

### Name Mismatches

| AC.ID | JDex says | Folder says | Suggested Action |
|-------|-----------|-------------|-----------------|
| 11.03 | Home insurance | Homeowners insurance | Reconcile names |

### +SUB Index Issues

| Category | Issue | Details |
|----------|-------|---------|
| 51.01 | Missing from index | +0004 folder exists, not in index |

5. Offer Fixes

After presenting the report, offer to fix issues:

Safe Fixes (do automatically with confirmation)

  • Add undocumented folders to JDex: Append new entries matching the folder names.
  • Update +SUB index files: Add missing entries to index files.

Requires User Decision

  • Orphaned JDex entries: Ask whether to create the missing folder or remove the JDex entry.
  • Name mismatches: Ask which name is correct (JDex or folder) and update the other.

Never Do Automatically

  • Delete folders: Even if they appear orphaned, never delete without explicit user confirmation.
  • Rename folders: Name changes can break references. Always confirm first.
  • Create new areas or categories: These are structural decisions.

6. Regenerate JDex (Optional)

If the user requests it, offer to regenerate the JDex entirely from the folder structure:

  1. Walk the filesystem and build a complete list of areas, categories, and IDs.
  2. Preserve any JDex-only metadata (cross-system references, notes, +SUB descriptions) from the existing JDex.
  3. Write the new JDex, merging filesystem reality with JDex metadata.
  4. Present the result for user approval before overwriting.

Warning: Regeneration loses any JDex entries that don't have corresponding folders. Always confirm before proceeding.


7. Multi-System Audit

When auditing multiple systems:

  1. Audit each system independently.
  2. Present per-system reports.
  3. Optionally check cross-system references: if P10.34.01 is referenced by F50.32.01, verify that both the source and the reference exist.
  4. Provide a combined summary at the end.

Johnny.Decimal Next Action Dashboard

This skill creates a unified, prioritized view of everything requiring attention across all Johnny.Decimal systems. It combines active tasks (from todo.txt), unprocessed inbox items, and items needing review into a single report ordered from most urgent to least urgent, followed by a "coming up" section for items approaching actionability.

This skill is read-only — it never modifies any files. It reads and reports.

For task parsing rules, read ../jd-task-manager/references/jdtodo-spec.md (the jdtodo.txt format specification).


1. Orientation: Discover the JD Environment

Before generating the report, build a mental map of the user's JD setup.

1.1 Locate the JD Root

The JD root folder is wherever the user's systems live. Common locations:

  • ~/Library/Mobile Documents/com~apple~CloudDocs/JD/ (iCloud Drive)
  • ~/Documents/JD/
  • ~/JD/
  • A project-specific folder the user designates

If you don't know the root, ask the user. If the user says "what should I do next" without further context, check the most common locations above. If you find exactly one, use it. If you find multiple or none, ask.

1.2 Identify Systems

List the top-level folders under the JD root. Each folder whose name matches the pattern [A-Z][0-9][0-9] * is a JD system (e.g., P10 Personal, W20 Work).

If the user has a single system (no SYS prefix), treat the entire JD root as one system.

If the user specified a system code as an argument (e.g., "next actions for P10"), limit scanning to that system only.

1.3 Load Each System's JDex

For every system you'll scan, read the JDex file at:

SYS/00-09 */00 */00.00 *JDex*

The JDex is needed to enrich task displays with human-readable descriptions for +AC.ID references. If the JDex is missing, you can still generate the report but cannot enrich JD codes — note this in the summary.


2. Scan Data Sources

For each system, locate and read these data sources. If a source doesn't exist, skip it and note the absence.

2.1 Active Tasks — 00.02 Tasks/todo.txt

Read and parse todo.txt using jdtodo.txt format rules (see the jdtodo-spec reference). For each task, extract:

  • State (incomplete, complete, cancelled)
  • Priority ((A) through (Z), or none)
  • Creation date
  • Description
  • Contexts (@context)
  • Projects (+project, +AC.ID)
  • Key:value pairs (due:, before:, t:, after:, id:, dep:, rec:, h:)
  • Notes (after ---)

Filter for actionable tasks. A task is actionable if ALL of these are true:

  • It is incomplete (not x or ~)
  • It is not hidden (h:1 absent)
  • Its threshold date has passed or is absent (t: date <= today, or no t:)
  • Its after: date has passed or is absent (after: date <= today, or no after:)
  • It does not have @someday context
  • It does not have due:someday
  • All dep: references point to completed tasks (or the referenced id: does not exist in the active task list)

Track separately:

  • Blocked tasks: Incomplete tasks whose dep: points to an incomplete task. Count these for the summary but do not include in the main report.
  • Waiting tasks: Tasks with @waiting context that are otherwise actionable. Include them in their normal bucket but count them separately for the summary.

2.2 Inbox — 00.01 Inbox/

List the contents of the inbox folder. Do NOT read or classify individual items — that is the inbox processor's job. Collect:

  • Total item count
  • File types present (.md, .pdf, .jpg, etc.)
  • Date of the most recently added item (from filesystem metadata or date-prefix in filename)

If the inbox is empty, skip this data source entirely.

2.3 Needs Review — 00.04 Needs review/

List items in the needs-review folder. For each item, collect:

  • Filename
  • Date added (from date-prefix in filename, or filesystem metadata)

If the folder doesn't exist or is empty, skip this data source.

2.4 Someday — 00.02 Tasks/someday.txt

Count the number of tasks in someday.txt (if it exists). This is for the summary statistics only — do not include someday tasks in the report body.

Also count tasks with @someday or due:someday in todo.txt that were excluded by the actionability filter.

2.5 Coming Up — Future Threshold Tasks

Identify tasks that are NOT yet actionable but will become actionable within the next 14 days:

  • Tasks with t:YYYY-MM-DD where the date is > today AND <= today + 14 days
  • Tasks with after:YYYY-MM-DD where the date is > today AND <= today + 14 days

These are not blocked or someday — they're simply waiting for their visibility window to open.


3. Categorize into Priority Buckets

Place each item into exactly one bucket — the highest-priority bucket it qualifies for. A task that qualifies for multiple buckets appears only in the first matching one.

3.1 Bucket Definitions

Process in this order (first match wins):

Bucket 1 — Overdue Actionable tasks where due: or before: date is before today. Show how many days overdue each task is.

Bucket 2 — Due Today Actionable tasks where due: or before: date equals today.

Bucket 3 — Inbox Unprocessed items in 00.01 Inbox/ folders. Shown as a count per system, not individual items.

Bucket 4 — Needs Review Items in 00.04 Needs review/ folders. Shown as individual items with filenames.

Bucket 5 — High Priority Actionable tasks with (A) priority that did not land in Overdue or Due Today.

Bucket 6 — Due This Week Actionable tasks where due: or before: is within the next 7 days (after today, up to and including today + 7 days). Excludes tasks already placed in a higher bucket.

Bucket 7 — Other Actionable All remaining actionable tasks — (B) through (Z) priority and unprioritized tasks that did not land in any bucket above.

Bucket 8 — Coming Up Tasks with t: or after: dates within the next 14 days that are not yet actionable. These are shown to help the user prepare.

3.2 Sorting Within Buckets

Within each bucket, sort tasks by:

  1. Priority — (A) first, then (B), then (C), ..., then unprioritized last
  2. Due date — earliest first (tasks with no due date sort last)
  3. Creation date — oldest first

3.3 Empty Buckets

If a bucket has zero items, omit that section entirely from the report. Only show sections that have content.


4. Generate the Report

4.1 Report Header

## Next Actions

**Date:** YYYY-MM-DD
**Systems:** [comma-separated system names, e.g., P10 Personal, W20 Work]

If scanning a single system, omit the "Systems" line and use the system name in the header:

## Next Actions — P10 Personal

**Date:** YYYY-MM-DD

4.2 Overdue Section

### Overdue (N)

| Pri | Task | Due | Overdue |
|-----|------|-----|---------|
| (A) | [P10] Submit quarterly tax estimate +N42.13.02 @laptop | 2026-02-05 | 5 days |
| (B) | [P10] Review tuition bill +V06.31.02 @laptop | 2026-02-08 | 2 days |

Show the [SYS] prefix only when displaying multiple systems.

4.3 Due Today Section

### Due Today (N)

| Pri | Task |
|-----|------|
| (A) | [W20] Respond to P0 incident follow-up +G24.21.05 @work |

4.4 Inbox Section

### Inbox (N items)

| System | Items | Newest |
|--------|-------|--------|
| P10 Personal | 8 items (.md, .pdf, .jpg) | 2026-02-09 |
| W20 Work | 3 items (.md, .txt) | 2026-02-08 |

Run `/jd:process-inbox` to classify and file these items.

For single-system reports, simplify:

### Inbox (8 items)

8 unprocessed items (.md, .pdf, .jpg). Newest: 2026-02-09.

Run `/jd:process-inbox P10` to classify and file these items.

4.5 Needs Review Section

### Needs Review (N items)

| System | Item | Date |
|--------|------|------|
| P10 | 2026-01-28 Meeting notes.md | Jan 28 |
| W20 | 2026-02-03 Budget spreadsheet.xlsx | Feb 3 |

4.6 High Priority Section

### High Priority (N)

| Task | Due |
|------|-----|
| [P10] Clean out garage +GarageSale +N42.12.05 | 2026-05-01 |
| [W20] Review contract terms +G24.31.05 @laptop | 2026-02-15 |

4.7 Due This Week Section

### Due This Week (N)

| Pri | Task | Due |
|-----|------|-----|
| (B) | [P10] Schedule dentist for Hannah @phone | Feb 12 |
| (B) | [P10] Water all houseplants @home | Feb 11 |

4.8 Other Actionable Section

### Other Actionable (N)

| Pri | Task | Due |
|-----|------|-----|
| (B) | [P10] Sort items for garage sale +GarageSale | Feb 20 |
| (C) | [W20] Update project documentation @laptop | — |
| — | [P10] Update emergency contacts | — |

Show — for tasks with no due date.

4.9 Coming Up Section

### Coming Up (next 14 days)

| Task | Actionable | Due |
|------|------------|-----|
| [P10] Renew car registration +N42.12.01 | Jun 1 (in 5 days) | Jun 30 |
| [W20] Start Q2 planning +G24.21.02 | Feb 20 (in 10 days) | Mar 1 |

These tasks are not yet actionable but will become visible soon.

Show both the date the task becomes actionable (t: or after: date) and its due date (if any). Include the "in N days" relative label.

4.10 JD Code Enrichment

When displaying tasks with +AC.ID or +SYS.AC.ID project tags, look up the code in the relevant system's JDex. If found, you may append the description after the task or use it in the table.

For example, if N42.13.02 maps to "Tax returns & estimates" in the JDex:

| (A) | Submit quarterly tax estimate +N42.13.02 @laptop | 2026-04-15 |

The JD code itself is usually enough context. Only add the description if the task text alone doesn't make the purpose clear.

4.11 Multi-System Display

When showing tasks from multiple systems:

  • Prefix each task with [SYS] (e.g., [P10], [W20])
  • Group inbox and needs-review items by system in their tables
  • Include all systems in the summary

When showing a single system:

  • Omit the [SYS] prefix
  • Omit per-system grouping in inbox/review tables

4.12 Summary

Always end the report with a summary section:

### Summary

| | Count |
|--|-------|
| Overdue | 2 |
| Due today | 1 |
| Inbox items | 11 |
| Needs review | 2 |
| High priority | 2 |
| Due this week | 3 |
| Other actionable | 8 |
| **Total actionable** | **16** |
| | |
| Blocked | 3 |
| Waiting (@waiting) | 2 |
| Someday | 5 |
| Coming up (14 days) | 2 |

**Recommended focus:** [one sentence suggesting where to start]

The "Recommended focus" line should follow this logic:

  • If overdue tasks exist: "Start with the N overdue tasks."
  • Else if due-today tasks exist: "Handle the N tasks due today."
  • Else if inbox has items: "Process inbox to surface any hidden urgencies."
  • Else if high-priority tasks exist: "Focus on the N high-priority items."
  • Otherwise: "No urgent items. Good time for a review or inbox check."

5. Filtering

The user may request a filtered view. Apply the filter AFTER scanning all data sources but BEFORE bucketing.

5.1 Filter by System

"next actions for P10" — Only scan the specified system.

5.2 Filter by Context

"what can I do @phone" — Only include tasks with the specified context. Inbox and needs-review items are still shown (they may contain relevant work).

5.3 Filter by Project

"what's next for +GarageSale" — Only include tasks with the specified project tag. Inbox and needs-review items are omitted (they haven't been classified).

5.4 Filter by Timeframe

"what's due this week" — Only include tasks in the Overdue, Due Today, and Due This Week buckets. Omit inbox, needs review, and lower-priority buckets.


6. Interaction Principles

6.1 Read-Only

This skill never modifies files. It reads task files, inbox contents, and needs-review items, then generates a report. No writes, no moves, no edits.

6.2 No Duplicate Work

Do not read inbox item contents or classify them — that's the inbox processor's job. Only count items and note their presence.

Do not modify task priorities or due dates — that's the task manager's job.

6.3 Actionable Suggestions

After the report, suggest relevant next steps using other skills:

  • If inbox has items: "Run /jd:process-inbox to classify inbox items."
  • If overdue tasks exist: "Use /jd:manage-tasks to reschedule or complete overdue tasks."
  • If someday count is high: "Use /jd:manage-tasks review to review someday items."

6.4 Repeat Invocations

If the user asks for the report again during the same session, regenerate it fresh — task states may have changed.


7. Error Handling

7.1 Missing Task Files

If 00.02 Tasks/todo.txt doesn't exist for a system:

  • Check if 00.02 Tasks.md exists (legacy format). If so, note it and suggest migration via /jd:manage-tasks.
  • If nothing exists, note "No task files found for [system]" in the summary.

7.2 Missing Inbox or Review Folders

If 00.01 Inbox/ or 00.04 Needs review/ doesn't exist, simply omit that data source. Do not warn about structural absence — not all systems use all standard zeros.

7.3 Unparseable Tasks

If a task line cannot be parsed:

  • Include it in the report with a [parse error] flag
  • Do not skip it — the user should know it exists
  • Continue processing remaining tasks

7.4 JDex Not Found

If a system's JDex is missing:

  • Generate the report without JD code enrichment
  • Note in the summary: "JDex not found for [system] — JD codes not enriched."

7.5 No Data Found

If all data sources are empty across all systems:

  • Report "Nothing to do!" with a clean summary showing all zeros
  • Suggest: "Good time to check if anything needs capturing."

Quick Reference: Priority Buckets

OrderBucketSourceCriteria
1Overduetodo.txtdue: or before: < today
2Due Todaytodo.txtdue: or before: = today
3Inbox00.01 Inbox/Any items present
4Needs Review00.04 Needs review/Any items present
5High Prioritytodo.txt(A) tasks not in above
6Due This Weektodo.txtdue: or before: within 7 days
7Other Actionabletodo.txtAll remaining actionable
8Coming Uptodo.txtt: or after: within 14 days

Quick Reference: Actionability Criteria

A task is actionable if ALL true:

  • Not completed (x) or cancelled (~)
  • Not hidden (h:1 absent)
  • Threshold passed (t: <= today, or no t:)
  • After date passed (after: <= today, or no after:)
  • No @someday context
  • No due:someday
  • All dep: resolved (blocking tasks completed or absent)

Johnny.Decimal +SUB Index Manager

This skill maintains +SUB index files within categories that use the AC.ID+NNNN or AC.ID+CODE extension pattern. It keeps index files in sync with the actual +SUB folders and helps create new entries.


1. Understand +SUB Extensions

+SUB extends the AC.ID notation for items that repeat across many instances within a single ID.

Numeric +SUB: AC.ID+NNNN

Zero-padded four-digit sequential number:

53.01+0001  weather-api
53.01+0002  task-runner
53.01+0003  auth-dashboard

Named +SUB: AC.ID+CODE

Short alphanumeric code:

11.01+REDD  The Red Door
11.01+OAKS  Oak Street Cafe
11.01+RIVR  Riverside Grill

When Each Format is Used

Numeric +NNNNNamed +CODE
Items are primarily sequentialItems have natural short codes
No inherent abbreviationAbbreviations are obvious and useful
Expect many entries (20+)Expect fewer, memorable entries
Example: projects, trips, campaignsExample: accounts, venues, people

2. Locate +SUB Categories

2.1 Find the System

Check common JD root locations and identify the target system. If the user specifies a system code and category, go directly there. Otherwise, scan for +SUB categories.

2.2 Identify +SUB Categories

A category uses +SUB if it contains folders matching the pattern:

AC.ID+NNNN Description/
AC.ID+CODE Description/

Scan the system's categories and list those with +SUB folders.

2.3 Find the Index File

Each +SUB category should have an index file. Common patterns:

  • AC.ID [Category] index.md (e.g., 51.01 Open-source project index.md)
  • AC.00 [Category] index.md (e.g., 51.00 Projects area index.md)

If no index file exists, offer to create one.


3. Scan Existing Entries

List all +SUB folders within the target category/ID. For each entry, capture:

  • The +SUB identifier (number or code)
  • The description (from folder name)
  • Whether the folder contains content or is empty
  • Creation date (from folder metadata or earliest file date)

4. Update the Index

4.1 Index File Format

The index file should list every +SUB entry with its identifier, name, creation date, and status:

# [Category name] Index

| +SUB | Name | Created | Status |
|------|------|---------|--------|
| +0001 | weather-api | 2025-06-01 | active |
| +0002 | task-runner | 2025-08-15 | active |
| +0003 | auth-dashboard | 2025-11-01 | archived |

For named +SUB:

# [Category name] Index

| +SUB | Name | Created | Status |
|------|------|---------|--------|
| +REDD | The Red Door | 2025-01-10 | active |
| +OAKS | Oak Street Cafe | 2025-03-22 | active |
| +RIVR | Riverside Grill | 2025-05-01 | active |

4.2 Sync Process

  1. Read the existing index file (if it exists).
  2. Compare index entries against actual +SUB folders.
  3. Add any folders that are missing from the index.
  4. Flag any index entries whose folders don't exist.
  5. Update the index file with the reconciled list.

4.3 Preserve Existing Format

If the user's index file uses a different format than the template above, match their existing format. Don't impose a new structure on an established index.


5. Create New +SUB Entries

When the user wants to add a new entry:

5.1 Determine the Next Identifier

For numeric +SUB:

  1. List all existing +NNNN entries in the category.
  2. Find the highest number.
  3. The next entry is that number + 1, zero-padded to 4 digits.
  4. Example: highest is +0003 → next is +0004.

For named +SUB:

  1. Ask the user for the entry name.
  2. Derive a short code (typically 4 uppercase letters from the name).
  3. Verify the code doesn't conflict with existing entries.
  4. Example: "Midnight Sun Brewing" → +MSUN.

5.2 Create the Folder

Create the +SUB folder:

AC.ID+NNNN Description/

or:

AC.ID+CODE Description/

5.3 Update the Index

Append the new entry to the index file.

5.4 Update the JDex

Add the new +SUB entry to the system's JDex under its parent ID:

- 53.01 Open-source projects
  - 53.01+0001 weather-api
  - 53.01+0002 task-runner
  - 53.01+0003 auth-dashboard
  - 53.01+0004 [new entry]     ← added

6. Archiving +SUB Entries

When a +SUB entry is no longer active:

  1. Update the status in the index file from "active" to "archived".
  2. Do not move or delete the folder — archived entries stay in place.
  3. Optionally note the archive date in the index.
  4. The folder and its contents remain accessible for reference.

7. Reporting

After any update, present a summary:

+SUB Index Update: [Category name]

Entries: N total (N active, N archived)
Added: [list of new entries, or "none"]
Issues: [list of mismatches, or "none"]

Next available number: +NNNN

Johnny.Decimal System Setup

This skill creates a new Johnny.Decimal system from scratch — building the folder structure, standard zeros, and initial JDex based on the user's needs.


1. Gather Requirements

Before creating anything, understand what the user needs.

1.1 Single or Multi-System?

Ask the user:

  • Single system: One organizational domain (e.g., just personal life, or just work). No system prefix needed — folders use plain AC.ID notation.
  • Multi-system: Multiple distinct domains (e.g., personal + work, or personal + work + child). Each system gets a SYS prefix using the [A-Z][0-9][0-9] format.

If the user already has JD systems, check the existing root to avoid conflicts.

1.2 System Identity

For each system to create, gather:

  • System code (multi-system only): A three-character [A-Z][0-9][0-9] identifier. Encourage memorable codes (e.g., P10 for personal, W20 for work). The code should be visually distinctive.
  • System name: A plain-English name (e.g., "Personal", "Work", "Jamie").
  • Root location: Where the system will live on disk. Common locations:
    • ~/Library/Mobile Documents/com~apple~CloudDocs/JD/ (iCloud Drive)
    • ~/Documents/JD/
    • ~/JD/

1.3 Areas and Categories

Walk the user through defining their areas. Provide guidance:

  • Maximum 10 areas (including 00-09 System)
  • Each area covers a major life/work domain
  • Fewer areas is better — compression over granularity
  • Area 00-09 is always created automatically for system management

For each area, ask about categories:

  • Maximum 10 categories per area
  • Categories are "where you work" — collections of similar things
  • Category names should be short and clear

For each category, ask if they have specific IDs in mind, or if they'll create IDs as content arrives.


2. Create the Folder Structure

2.1 System Root

Create the system root folder:

  • Single system: [Root]/ (e.g., ~/JD/)
  • Multi-system: [Root]/SYS Name/ (e.g., ~/JD/P10 Personal/)

2.2 Area Folders

Create area folders using the format AC-range Description:

00-09 System
10-19 [Area name]
20-29 [Area name]
...

2.3 Category Folders

Within each area, create category folders using the format AC Description:

00 System management
01 [Category name]
11 [Category name]
12 [Category name]
...

2.4 Standard Zeros (System Level)

Always create these in 00-09 System/00 System management/:

FolderPurpose
00.00 JDex.mdMaster index (file, not folder)
00.01 Inbox/Unsorted capture bucket
00.02 Tasks.mdAction items and follow-ups (file)
00.03 Processing log.mdRecord of inbox processing sessions (file)

Optionally create if the user wants them:

FolderPurpose
00.04 Needs review/Items awaiting user decision
00.08 Someday/Non-urgent ideas and parking lot
00.09 Archive/Completed or stale items

2.5 ID Folders

If the user specified initial IDs during requirements gathering, create them using the format AC.ID Description:

11.01 Mortgage & title/
11.02 Property tax/
11.03 Homeowners insurance/

3. Generate the JDex

Create 00.00 JDex.md with a complete listing of every area, category, and ID in the system.

JDex Format

# [SYS] JDex

## 00-09 System
- 00.00 JDex ← this file
- 00.01 Inbox
- 00.02 Tasks
- 00.03 Processing log

## 10-19 [Area name]

### 11 [Category name]
- 11.01 [ID description]
- 11.02 [ID description]

### 12 [Category name]
- 12.01 [ID description]

## 20-29 [Area name]
...

JDex Rules

  • Every folder that exists must have a JDex entry
  • Every JDex entry must have a corresponding folder
  • +SUB entries are listed inline under their parent ID
  • Cross-system references use arrow notation: → P10.34.01

4. Initialize Task and Log Files

4.1 Tasks File

Create 00.02 Tasks.md:

# [System name] Tasks

Tasks extracted during inbox processing and daily use.

---

<!-- Add tasks below this line -->

4.2 Processing Log

Create 00.03 Processing log.md:

# [System name] Processing Log

Record of inbox processing sessions.

---

<!-- Processing entries will be appended below -->

5. Verification

After creating the structure:

  1. List the complete folder tree to depth 3 and present it to the user for review.
  2. Display the JDex so the user can verify all entries are correct.
  3. Confirm iCloud sync (if applicable): Verify folders appear correctly.
  4. Note next steps: Suggest the user start capturing items into their inbox and run /jd:process-inbox when ready.

6. Multi-System Considerations

When setting up multiple systems at once:

  • Each system gets its own independent JDex
  • Each system gets its own standard zeros
  • Cross-system references should be noted during setup if known (e.g., "F50.32.01 will reference P10.34.01 for health insurance")
  • Suggest the user set up one system fully before moving to the next

7. Templates for Common System Types

Offer these as starting points when the user isn't sure what areas to create:

Personal Life System

00-09 System
10-19 Home & property
20-29 Family & relationships
30-39 Money & legal
40-49 Health & wellness
50-59 Projects & hobbies
60-69 Travel & experiences

Work System

00-09 System & employment
10-19 [Primary work domain]
20-29 Career development
30-39 Professional visibility

Child/Dependent System

00-09 System
10-19 Identity & documents
20-29 School / academics
30-39 Health & medical
40-49 Activities & interests

These are suggestions, not prescriptions. The user's actual needs should drive the structure.

Johnny.Decimal Task Manager

This skill manages tasks in Johnny.Decimal systems using the jdtodo.txt plain-text format. It reads, creates, completes, cancels, and modifies tasks stored in todo.txt files within 00.02 Tasks/ folders. It also handles done.txt (completed and cancelled tasks) and someday.txt (deferred items).

Before processing, read references/jdtodo-spec.md for the complete jdtodo.txt format specification.


1. Orientation: Discover the JD Environment

Before touching any files, build a mental map of the user's JD setup.

1.1 Locate the JD Root

The JD root folder is wherever the user's systems live. Common locations:

  • ~/Library/Mobile Documents/com~apple~CloudDocs/JD/ (iCloud Drive)
  • ~/Documents/JD/
  • ~/JD/
  • A project-specific folder the user designates

If you don't know the root, ask the user. If the user says "show my tasks" without further context, check the most common locations above. If you find exactly one, confirm it. If you find multiple or none, ask.

1.2 Identify Systems

List the top-level folders under the JD root. Each folder whose name matches the pattern [A-Z][0-9][0-9] * is a JD system (e.g., P10 Personal, W20 Work, C40 Citywide).

If the user has a single system (no SYS prefix), treat the entire JD root as one system.

1.3 Load Each System's JDex

For every system you'll work with, read the JDex file at:

SYS/00-09 */00 */00.00 *JDex*

The JDex is needed to validate JD codes on tasks and to display human-readable descriptions alongside +AC.ID references. If the JDex is missing, you can still manage tasks but cannot validate JD code references — flag this to the user.

1.4 Locate Task Files

For each system, look for task files at:

SYS/00-09 */00 */00.02 Tasks*/todo.txt
SYS/00-09 */00 */00.02 Tasks*/done.txt
SYS/00-09 */00 */00.02 Tasks*/someday.txt

Legacy detection: If a file named 00.02 Tasks.md exists (instead of a 00.02 Tasks/ directory), this is the legacy markdown-checkbox format from the system setup workflow. See §10 for migration guidance.

If no task files exist at all, offer to create the 00.02 Tasks/ directory with an empty todo.txt.


2. Parse Tasks

Each line in todo.txt (and done.txt, someday.txt) is a task. Parse using these rules from the jdtodo.txt specification.

2.1 Logical Lines

A task is one logical line. If a line ends with \ (backslash as the very last character, no trailing whitespace), the next physical line is a continuation of the current task's note. Gather all continuation lines before parsing.

Skip blank lines and any lines that are entirely whitespace.

2.2 Task States

Determine the task state from the line prefix:

PrefixStateFile
x YYYY-MM-DDCompletedone.txt
~ YYYY-MM-DDCancelleddone.txt
(A) through (Z)Incomplete (with priority)todo.txt
Anything elseIncomplete (no priority)todo.txt

2.3 Priority and Dates

For incomplete tasks:

  1. If the line starts with (X) where X is A–Z, extract the priority.
  2. After priority (or at line start if no priority), check for a date in YYYY-MM-DD format — this is the creation date.

For complete/cancelled tasks:

  1. After the x or ~ marker, the first date is the completion/cancellation date.
  2. The second date (if present) is the creation date.

2.4 Contexts and Projects

Scan the task body (everything before --- if a note exists) for:

  • Contexts: tokens matching @non-whitespace (e.g., @phone, @laptop, @waiting, @someday)
  • Projects: tokens matching +non-whitespace (e.g., +GarageSale, +N42.12.05)

JD code detection regex for project tags:

\+([A-Z]\d{2}\.)?\d{2}\.\d{2}(\+[A-Za-z0-9]+)?

This matches +AC.ID, +SYS.AC.ID, +AC.ID+SUB, and +SYS.AC.ID+SUB.

2.5 Key:Value Extensions

Extract recognized key:value pairs from the task body:

KeyValue formatPurpose
dueYYYY-MM-DD or somedayHard deadline
beforeYYYY-MM-DD or somedaySoft deadline
tYYYY-MM-DD or somedayThreshold / visibility gate (user deferral)
afterYYYY-MM-DD or somedayVisibility gate (external constraint)
idNon-whitespace, no colonsTask identifier
depNon-whitespace, no colonsBlocked by another task
supNon-whitespace, no colonsSubtask of another task
rec[+]N[d|w|m|y|b]Recurrence interval
h1Hidden from default views
priA–ZPreserved priority (on completed tasks)

Preserve any unrecognized key:value pairs when modifying tasks.

2.6 Notes

If the task body contains --- (space-hyphen-hyphen-hyphen-space), everything after the first occurrence is the note. The note may span multiple physical lines via \ continuation. Leading whitespace on continuation lines is trimmed.

Key:value pairs in the note are freeform text — do NOT parse them as task metadata.


3. List and Filter Tasks

3.1 Default View

When the user asks to see their tasks without specific filters, show all actionable tasks. A task is actionable if ALL of these are true:

  • It is incomplete (not x or ~)
  • It is not hidden (h:1 absent)
  • Its threshold date has passed or is absent (t: date ≤ today, or no t:)
  • Its after: date has passed or is absent (after: date ≤ today, or no after:)
  • It does not have @someday context
  • It does not have due:someday
  • All dep: references point to completed tasks (or the referenced id: does not exist in the active task list)

Tasks with unresolved dependencies are shown in a separate Blocked section rather than hidden entirely.

3.2 Filter by Context

When the user specifies a context (e.g., "show me @phone tasks"), show only tasks that have that context tag. Common filters:

  • @phone — calls to make
  • @laptop — computer work
  • @errands — out-of-house tasks
  • @waiting — blocked on someone else
  • @someday — not currently actionable
  • @agenda — discuss at next meeting

3.3 Filter by Project or JD Code

When the user specifies a project or JD code:

  • +GarageSale — all tasks in that named project
  • +N42.12.05 — all tasks referencing that JD ID
  • +N42.12 — all tasks referencing any ID in that JD category

3.4 Filter by Priority

Show tasks at or above a given priority:

  • "show priority A tasks" → only (A) tasks
  • "show high priority" → (A) and (B) tasks
  • "show all priorities" → all tasks grouped by priority

3.5 Filter by Date

  • overdue: Tasks where due: or before: date is before today
  • due today: Tasks where due: is today
  • due this week: Tasks where due: is within the next 7 days
  • upcoming: Tasks where due: is within the next 14 or 30 days
  • no due date: Tasks with no due: or before: tag

3.6 Dependency Resolution

Build the dependency graph from id:, dep:, and sup: tags:

  1. Index all tasks by their id: value.
  2. For each task with dep:X, check if id:X exists and is incomplete.
  3. If id:X is incomplete, the task is blocked.
  4. If id:X is complete (in done.txt) or doesn't exist, the dependency is resolved.

Show blocked tasks in a separate section with the blocking task identified:

### Blocked

(B) Sort items into keep/sell/donate +GarageSale dep:garage-clean
    ↳ blocked by: (A) Clean out garage for sale [garage-clean]

For sup: relationships, show subtask grouping when listing by project:

### +GarageSale

(A) Clean out garage for sale id:garage-clean due:2026-05-01
  ├─ (B) Sort items into keep/sell/donate sup:garage-clean
  ├─ (B) Sweep and mop garage floor sup:garage-clean
  └─ (C) Arrange sale items on tables sup:garage-clean dep:sort-items

3.7 Grouping

Default grouping is by priority. The user may request grouping by:

  • System: Group tasks by JD system (for cross-system views)
  • Project: Group by +project or +AC.ID tags
  • Context: Group by @context tags
  • Due date: Group into overdue / today / this week / later / no date
  • Priority: Group by (A), (B), (C), etc.

3.8 Cross-System View

When no system is specified and multiple systems have task files, merge all tasks and show system context. Prefix each task's display with its system code if it's identifiable from +SYS.AC.ID tags or from which system's todo.txt it came from:

## All Systems — 15 active tasks

### Priority A
[P10] (A) Submit quarterly tax estimate +N42.13.02 @laptop due:2026-04-15
[W20] (A) Respond to P0 incident follow-up +G24.21.05 @work due:2026-02-10

### Priority B
[P10] (B) Schedule dentist for Hannah +H11.25.01 @phone before:2026-03-01

3.9 JD Code Enrichment

When displaying tasks with JD code project tags, look up the code in the system's JDex and show the ID description:

(A) Submit quarterly tax estimate +N42.13.02 @laptop due:2026-04-15
    ↳ N42.13.02 = Tax returns & estimates

This helps the user understand the JD cross-reference without leaving the task view.


4. Add Tasks

4.1 Constructing a Task Line

Build a well-formed jdtodo.txt line from user input. The minimum requirement is a task description — everything else is optional. The line format is:

[(priority)] [creation-date] description [@contexts] [+projects] [key:values] [ --- note]

4.2 Creation Date

Always add today's date as the creation date on new tasks.

4.3 Priority

If the user specifies a priority, add it. If they don't mention priority, do not add one — unprioritized tasks are valid. Only ask about priority if the task sounds urgent or time-sensitive and the user didn't specify.

4.4 JD Code Integration

When the user mentions a JD location or the task clearly relates to a JD ID:

  1. Add the appropriate +AC.ID or +SYS.AC.ID project tag.
  2. Validate the code against the JDex. If the code doesn't exist, warn the user and ask whether to use it anyway or choose a different ID.
  3. If the user describes a domain but doesn't specify a JD code (e.g., "add a task about insurance"), suggest relevant IDs from the JDex.

4.5 Contexts

If the task description implies a context, suggest it:

  • Phone calls → @phone
  • Computer work → @laptop
  • Errands or physical locations → @errands
  • Waiting on someone → @waiting
  • Meeting discussion items → @agenda

Add suggested contexts only if the user confirms or if the mapping is obvious (e.g., "call the dentist" clearly gets @phone).

4.6 Dates

When the user mentions a deadline or timing:

  • "by Friday" / "due next week" → convert to due:YYYY-MM-DD
  • "before the party" → ask for a specific date, then use before:YYYY-MM-DD
  • "not until June" / "after surgery" → convert to after:YYYY-MM-DD or t:YYYY-MM-DD
  • "someday" / "eventually" → use due:someday or @someday

Use due: for hard deadlines, before: for soft targets, t: for user deferrals, and after: for external constraints. When in doubt, ask which semantic the user intends.

4.7 Relationships

If the task is part of a project that has existing tasks with id: tags:

  1. Show the existing task graph for that project.
  2. Offer to set sup: (subtask) or dep: (blocked by) links.
  3. If the new task should be identifiable by other tasks, suggest an id: — keep it short and descriptive (e.g., id:post-signs).

4.8 Notes

If the user provides additional context beyond the task description, add it as a note after ---. For multi-line notes, use \ continuation:

(B) 2026-02-09 Schedule vet appointment @phone --- Last checkup was October. \
    Needs rabies booster.

4.9 Recurrence

If the task repeats:

  • "every 3 days" → rec:3d
  • "weekly" → rec:1w
  • "monthly on the 1st" → rec:+1m (strict, anchored to date)
  • "every 2 weeks" → rec:2w
  • "every business day" → rec:1b

Use strict mode (+ prefix) when the task is calendar-anchored (rent, reports). Use non-strict when the interval from last completion matters (watering plants).

4.10 Which File

  • New tasks go in todo.txt by default.
  • Tasks with @someday or due:someday may optionally go in someday.txt if the user has a separate someday file. Ask the user their preference if both options are available.

4.11 Confirm Before Writing

Before adding the task, show the user the complete formatted line:

Adding to P10 todo.txt:
(B) 2026-02-09 Schedule vet appointment for Max +N42.25.01 @phone before:2026-03-01 --- Last checkup was October. Needs rabies booster.

Proceed after confirmation, or adjust based on feedback.


5. Complete and Cancel Tasks

5.1 Identifying the Task

When the user says "complete the insurance task" or "mark that done," identify the target task:

  1. Search active tasks for keyword matches in the description.
  2. If the user references a JD code, id:, project, or context, use those to narrow the search.
  3. If exactly one task matches, confirm it with the user.
  4. If multiple tasks match, present the candidates and ask which one(s).
  5. If no tasks match, say so and offer to list tasks for the user to choose.

5.2 Completing a Task

To mark a task complete:

  1. Strip the (X) priority from the line start (if present).
  2. Prepend x YYYY-MM-DD using today's date as the completion date.
  3. If the task had a priority, add pri:X to the end of the task body (before any --- note).
  4. Preserve all other content: description, contexts, projects, key:value pairs, and notes.

Before completion:

(A) 2026-02-01 Call Goodwill +GarageSale @phone due:2026-02-15

After completion:

x 2026-02-09 2026-02-01 Call Goodwill +GarageSale @phone due:2026-02-15 pri:A

5.3 Cancelling a Task

To cancel a task:

  1. Strip the (X) priority (if present).
  2. Prepend ~ YYYY-MM-DD using today's date as the cancellation date.
  3. If the task had a priority, add pri:X.
  4. Ask the user for a cancellation reason and append it as a note.

Before cancellation:

(B) 2026-02-01 Order extra tables +GarageSale

After cancellation:

~ 2026-02-09 2026-02-01 Order extra tables +GarageSale pri:B --- Lauren has enough tables.

5.4 Handle Recurrence

When completing a task that has a rec: tag:

  1. Complete the original task as described in §5.2.
  2. Create a new incomplete task with the same description, projects, contexts, key:value pairs (except pri: — restore the original priority), and notes.
  3. Shift date fields forward by the recurrence interval:

Non-strict (no + prefix, e.g., rec:3d): Calculate from today's date (the completion date).

Strict (+ prefix, e.g., rec:+1m): Calculate from the original due: date.

  1. Shift all date fields: due:, t:, before:, after:. Preserve the gap between t: and due: (if t: was 15 days before due:, the new t: should be 15 days before the new due:).
  2. Set the creation date on the new task to today (the completion date).

Example — non-strict:

# Original (completed today, Feb 12):
x 2026-02-12 2026-02-09 Water all houseplants @home rec:3d due:2026-02-09 → done.txt

# New task:
(B) 2026-02-12 Water all houseplants @home rec:3d due:2026-02-15 → todo.txt

Example — strict:

# Original (completed today, Feb 1):
x 2026-02-01 2026-01-01 Pay rent rec:+1m due:2026-02-01 → done.txt

# New task (based on original due date, not completion date):
2026-02-01 Pay rent rec:+1m due:2026-03-01 → todo.txt

5.5 Move to done.txt

After completing or cancelling a task:

  1. Remove the task line (and any \ continuation lines) from todo.txt.
  2. Append the completed/cancelled line to done.txt.
  3. If done.txt does not exist, create it.
  4. If the task was recurring, the new occurrence stays in todo.txt.

5.6 Batch Completion

When completing multiple tasks at once, present a confirmation table:

Complete these tasks?

| # | Task | Status |
|---|------|--------|
| 1 | Call Goodwill +GarageSale @phone | → done.txt |
| 2 | Water houseplants @home rec:3d | → done.txt + new occurrence |
| 3 | File insurance claim +N42.11.03 | → done.txt |

Proceed with all 3? [y/n/select specific]

6. Modify Tasks

6.1 Change Priority

Update or add (X) at the start of the task line. If the task already has a priority, replace it. If it has no priority, insert before the creation date (or before the description if no creation date).

6.2 Add or Change Dates

Add or modify due:, before:, t:, after: tags. If the tag already exists, replace its value. If new, append to the task body (before ---).

6.3 Add Contexts or Projects

Append @context or +project tags to the task body. Check for duplicates before adding.

6.4 Add or Update Notes

  • If the task has no note, add --- followed by the note text.
  • If the task already has a note, append to it (add a \ continuation if needed for multiline).

6.5 Set Up Relationships

Add id:, dep:, or sup: tags to the task body:

  • When adding id:, verify the identifier is unique within the file.
  • When adding dep:, verify the referenced id: exists.
  • When adding sup:, verify the referenced id: exists.

6.6 Move to Someday

To defer a task indefinitely:

  1. Add @someday or change due: to due:someday.
  2. If the user has a separate someday.txt, offer to move the task there.
  3. Remove t: and after: dates if present (they're superseded by someday status).

6.7 Reactivate from Someday

To bring a task back from someday:

  1. Remove @someday context and due:someday (if present).
  2. If the task is in someday.txt, move it to todo.txt.
  3. Ask the user for a new due date or leave undated.

7. Review Mode

Review mode is a guided walkthrough for periodic task maintenance — typically weekly.

7.1 Someday Review

Present each task in someday.txt (or tasks with @someday/due:someday in todo.txt):

For each task, offer:

  • Keep: Leave as someday.
  • Activate: Move to todo.txt, set a due date, remove @someday.
  • Cancel: Mark cancelled with reason, move to done.txt.

7.2 Deferred Tasks

Show tasks whose t: or after: date has passed — these are now actionable but may have been overlooked:

These tasks are now actionable:

(B) Renew car registration +N42.12.01 t:2026-06-01 due:2026-06-30
    ↳ Threshold date passed (was deferred until Jun 1)

Also show tasks with t: or after: dates in the next 7 days — coming up soon.

7.3 Stale Tasks

Identify incomplete tasks that may be stale:

  • Created more than 30 days ago with no due date and no recent modification
  • No priority set
  • Not part of an active project

For each stale task, offer: keep as-is, set a due date, move to someday, or cancel.

7.4 Dependency Check

Show tasks whose blocking dependencies have been resolved since the last review — these are newly actionable:

Newly unblocked:

(B) Post signs around neighborhood +GarageSale dep:plan-sale
    ↳ plan-sale was completed on 2026-02-05

7.5 Overdue Summary

Present all tasks past their due: date, sorted by how overdue:

Overdue tasks:

(A) Respond to P0 follow-up +G24.21.05 due:2026-02-10 [9 days overdue]
(B) Review tuition bill +V06.31.02 due:2026-02-28 [past due]

For each, offer: complete (if done), reschedule (set new due date), or cancel.


8. JD Integration

8.1 Cross-Referencing with JDex

When a task uses +AC.ID or +SYS.AC.ID project tags:

  1. Look up the code in the relevant system's JDex.
  2. If found, display the JDex description alongside the task when showing task lists.
  3. If not found, warn the user: "JD code +N42.12.05 is not in the JDex. Create the ID, or use a different code?"

8.2 Context from JD System

When displaying tasks, enrich JD code references:

(A) Clean out garage for sale +N42.12.05 due:2026-05-01
    ↳ N42.12.05 = Garage maintenance (in P10 Personal)

This is informational — it helps the user remember what the JD code refers to without switching context.

8.3 Task Extraction Compatibility

The inbox processor skill (§4 of jd-inbox-processor) extracts tasks in markdown-checkbox format and appends them to 00.02 Tasks. When both skills are in use:

  • If the task file is todo.txt (jdtodo.txt format), extracted tasks should be written in jdtodo.txt format instead of markdown checkboxes.
  • The jdtodo.txt format is preferred when a todo.txt file exists.
  • If only 00.02 Tasks.md exists (legacy format), the inbox processor's format is compatible until migration (see §10).

8.4 Multi-System Tasks

A single todo.txt may reference multiple systems via +SYS.AC.ID tags. Alternatively, each system may have its own todo.txt. Handle both approaches:

  • Single file: All tasks in one todo.txt, system identified by project tags.
  • Per-system files: Separate todo.txt per system, merged for cross-system views.

When displaying cross-system views, avoid duplicate id: confusion by mentally namespacing — if two systems both have an id:plan, show the system context to disambiguate.


9. Interaction Principles

9.1 When to Ask vs. When to Act

  • Act without asking: Listing tasks, showing filtered views, resolving dependency graphs, enriching JD code references. These are read-only and safe.
  • Confirm before acting: Completing tasks, cancelling tasks, moving tasks between files (todo.txt ↔ done.txt ↔ someday.txt), modifying tasks the user has specifically identified. Present the change and get a "yes."
  • Always ask: Deleting task lines (prefer moving to done.txt — never truly delete without explicit user confirmation), modifying tasks that the user hasn't specifically identified, creating task files or directories.

9.2 Task Identification

When the user refers to a task by description ("the insurance one," "that garage sale task"), use these signals to identify it:

  1. Keywords in the task description
  2. JD codes or project tags mentioned by the user
  3. Context tags (@phone, @laptop)
  4. Priority level
  5. Recency — if the user just added or discussed a task, it's likely the one they mean

If ambiguous, present the top 2–3 candidates:

I found 2 tasks matching "insurance":

  1. (A) Call insurance company about claim +N42.11.03 @phone
  2. (C) Research new homeowner's insurance quotes +N42.11.03 @laptop

Which one?

9.3 Format Preservation

When modifying todo.txt:

  • Preserve all existing formatting, whitespace, and ordering.
  • Append new tasks at the end of the file.
  • Do not re-sort the file unless the user explicitly asks.
  • When removing a completed task, remove the exact line(s) including any \ continuation lines.
  • Preserve blank lines and any comment-like lines (though jdtodo.txt doesn't formally define comments, users may have them).

10. Error Handling

10.1 Task File Missing

If todo.txt doesn't exist at the expected location:

  1. Check if a 00.02 Tasks/ directory exists. If so, create todo.txt in it.
  2. If only 00.02 Tasks.md exists (flat file), see §10.2.
  3. If nothing exists, offer to create the 00.02 Tasks/ directory with an empty todo.txt.

10.2 Legacy Format Migration

If 00.02 Tasks.md exists with markdown-checkbox tasks:

- [ ] Call the insurance company
- [x] File the tax return
- [ ] Schedule dentist appointment

Offer to migrate to jdtodo.txt format:

  1. Convert - [ ] description → YYYY-MM-DD description (using today's date as creation date, since the original has none).
  2. Convert - [x] description → x YYYY-MM-DD description (using today as completion date).
  3. Extract any JD references, contexts, or dates from the markdown text and convert to proper tags.
  4. Write the converted tasks to 00.02 Tasks/todo.txt (completed to done.txt).
  5. Rename 00.02 Tasks.md to 00.02 Tasks.md.bak (do not delete).

Always confirm the migration plan with the user before executing.

10.3 Invalid JD Codes

If a task references a +AC.ID that isn't in the JDex:

  • When listing: Show the task but flag the invalid reference.
  • When adding: Warn before writing and offer alternatives.
  • Do not block operations on tasks with invalid codes — they may be intentional placeholders.

10.4 Circular Dependencies

If dep: chains form a cycle (A depends on B, B depends on A):

  • Warn the user about the cycle.
  • Show which tasks are involved.
  • Suggest removing one of the dependencies to break the cycle.
  • Do not modify anything automatically.

10.5 Duplicate Task IDs

If multiple tasks in the same file have the same id: value:

  • Warn the user when the duplicate is detected.
  • Show both tasks with the duplicate ID.
  • Suggest renaming one of them.

10.6 File Write Errors

If writing to a file fails (permissions, disk full, etc.):

  • Report the error clearly.
  • Do not attempt to modify the original file again.
  • Show the user the change that was attempted so they can apply it manually.

11. Post-Action Summary

After any write operation (add, complete, cancel, modify), present a summary:

Task update complete.

P10 Personal: 12 active, 3 overdue
  Completed: 2 tasks (moved to done.txt)
  Recurring: 1 new occurrence generated
  Added: 1 new task

W20 Work: 5 active, 1 overdue
  Completed: 1 task (moved to done.txt)

For review sessions, provide a more detailed summary:

Weekly review complete.

Someday: 3 reviewed → 1 activated, 1 cancelled, 1 kept
Deferred: 2 tasks now actionable
Stale: 1 task moved to someday
Overdue: 3 tasks rescheduled
Newly unblocked: 1 task

Quick Reference: Task File Locations

SYS/00-09 System/00 System management/00.02 Tasks/
├── todo.txt       # Active and deferred tasks
├── done.txt       # Completed and cancelled tasks
└── someday.txt    # @someday items (optional)

Quick Reference: Task States

StateLine prefixStored in
Incomplete(none, or (A))todo.txt
Completex YYYY-MM-DDdone.txt
Cancelled~ YYYY-MM-DDdone.txt
Someday@someday or due:somedaysomeday.txt (optional) or todo.txt
Hiddenh:1todo.txt (excluded from views)

Quick Reference: Date Tags

TagMeaningVisibility effect
due:YYYY-MM-DDHard deadlineOverdue highlighting
before:YYYY-MM-DDSoft deadlineSame as due: for display
t:YYYY-MM-DDDon't show untilHidden before date
after:YYYY-MM-DDCan't start untilHidden before date
due:somedayIndefiniteHidden from default views

Commands 6

Audit JDex

Compare a system's JDex against its actual folder structure, flagging orphaned entries, undocumented folders, name mismatches, and +SUB index issues.

Arguments

$ARGUMENTS may contain a system code (e.g., P10) to audit a specific system. If no argument is provided, list all available systems and ask which to audit.

Workflow

  1. Load the target system's JDex.
  2. Snapshot the filesystem to depth 3.
  3. Compare JDex entries against folders:
    • Orphaned JDex entries (in JDex, no folder)
    • Undocumented folders (folder exists, not in JDex)
    • Name mismatches between JDex and folder names
  4. Check +SUB index files against +SUB folders.
  5. Report findings in a structured table.
  6. Offer fixes: Add missing JDex entries, update +SUB indexes, or flag items that need user decisions.

Safe Fixes

  • Adding undocumented folders to the JDex
  • Updating +SUB index files with missing entries

Requires User Decision

  • Orphaned JDex entries (create folder or remove entry?)
  • Name mismatches (which name is correct?)
  • Deleting or renaming any folder

Examples

/jd:jdex-audit
/jd:jdex-audit P10
/jd:jdex-audit F50

Manage Tasks

View, add, complete, cancel, and modify tasks in Johnny.Decimal 00.02 Tasks/ folders using the jdtodo.txt format. Handles todo.txt, done.txt, and someday.txt files.

Arguments

$ARGUMENTS may contain:

  • A system code (e.g., P10) to target a specific system's tasks.
  • An action keyword: add, complete, cancel, list, modify, review.
  • Filter criteria: priority (A), context (@phone), project (+GarageSale), JD code (+N42.12.05), or date range (overdue, due:this-week).
  • No arguments to list all actionable tasks across all systems.

Workflow

  1. Discover the JD root and available systems.
  2. Locate task files at 00.02 Tasks/ in each system (todo.txt, done.txt, someday.txt).
  3. Parse todo.txt files using jdtodo.txt format rules.
  4. Execute the requested action (list, add, complete, cancel, modify, review).
  5. Handle recurrence: When completing a recurring task, generate the next occurrence and keep the original in done.txt.
  6. Archive: Move completed and cancelled tasks to done.txt.
  7. Resolve dependencies: Show blocked vs. actionable tasks.
  8. Summarize changes made.

Actions

  • list (default): Show actionable tasks with filtering and grouping.
  • add: Create a new task with priority, dates, contexts, projects, and JD codes.
  • complete: Mark one or more tasks as done, handle recurrence, move to done.txt.
  • cancel: Mark tasks as cancelled with reason, move to done.txt.
  • modify: Change priority, add dates, add notes, update contexts or projects.
  • review: Show someday items and deferred tasks for weekly review.

Examples

/jd:manage-tasks
/jd:manage-tasks P10
/jd:manage-tasks P10 add
/jd:manage-tasks list @phone
/jd:manage-tasks list overdue
/jd:manage-tasks review

Next Action Dashboard

Generate a prioritized report of everything requiring attention across Johnny.Decimal systems — combining active tasks, unprocessed inbox items, and items needing review into a single view ordered from most urgent to least urgent.

Arguments

$ARGUMENTS may contain:

  • A system code (e.g., P10) to limit the report to a specific system.
  • A context filter (@phone, @laptop, @errands).
  • A project filter (+GarageSale, +N42.12.05).
  • A timeframe filter (this-week).
  • No arguments to show all systems with all actionable items.

Workflow

  1. Discover the JD root and available systems.
  2. Scan data sources per system:
    • 00.02 Tasks/todo.txt — active tasks
    • 00.01 Inbox/ — unprocessed item counts
    • 00.04 Needs review/ — items requiring decisions
    • 00.02 Tasks/someday.txt — deferred item count
  3. Parse tasks using jdtodo.txt format and filter for actionable items.
  4. Categorize into priority buckets: overdue, due today, inbox, needs review, high priority, due this week, other actionable, coming up.
  5. Generate a markdown report with one section per non-empty bucket.
  6. Summarize with counts, blocked/waiting stats, and recommended focus.

Priority Order (Highest to Lowest)

  1. Overdue tasks
  2. Due today
  3. Inbox items (unknown urgency)
  4. Needs review items
  5. High priority (A) tasks
  6. Due this week
  7. Other actionable tasks
  8. Coming up (threshold dates approaching within 14 days)

Examples

/jd:next-action
/jd:next-action P10
/jd:next-action @phone
/jd:next-action +GarageSale
/jd:next-action this-week

See Also

  • /jd:manage-tasks — View, add, complete, and modify tasks
  • /jd:process-inbox — Classify and file inbox items

Process Johnny.Decimal Inbox

Process items in one or more Johnny.Decimal 00.01 Inbox folders. Each item is read, classified against the JDex and folder structure, and moved to the correct ID location.

Arguments

$ARGUMENTS may contain a system code (e.g., P10) to process a specific system's inbox. If no argument is provided, discover all systems and their inboxes, then ask which to process.

Workflow

  1. Discover the JD root and available systems.
  2. Load the target system's JDex and folder structure.
  3. List inbox contents and report item count, types, and date range.
  4. Classify each item using the JDex as the primary reference.
  5. File items to their destination ID folders with date-prefix naming.
  6. Extract tasks from items that contain action items.
  7. Log every action to the processing log at 00.03 Processing log.md.
  8. Summarize what was processed, filed, and flagged.

Classification Confidence

  • High confidence: File without asking.
  • Medium confidence: Recommend a destination and ask the user to confirm.
  • Low confidence: Present 2–3 candidate locations and ask the user to choose.

Batch Mode

For inboxes with many items, present a table of proposed filings and let the user approve, modify, or flag specific items before executing.

Examples

/jd:process-inbox
/jd:process-inbox P10
/jd:process-inbox W20

Set Up a Johnny.Decimal System

Create a new Johnny.Decimal system from scratch — folders, standard zeros, and initial JDex.

Arguments

No required arguments. The command will walk the user through an interactive setup process.

Workflow

  1. Ask whether this is a single-system or multi-system setup.
  2. Gather system identity: code (if multi-system), name, and root location.
  3. Define areas: Walk through area definitions (max 10 including 00-09).
  4. Define categories: For each area, define categories (max 10 per area).
  5. Define initial IDs: Optionally pre-create ID folders within categories.
  6. Create structure: Build all folders on disk.
  7. Generate JDex: Write the complete index at 00.00 JDex.md.
  8. Initialize files: Create 00.02 Tasks.md and 00.03 Processing log.md.
  9. Verify: Display the complete folder tree for user review.

Templates

Offer starting templates for common system types:

  • Personal life: Home, family, money, health, projects, travel, hobbies
  • Work: System/employment, primary work domain, career, visibility
  • Child/dependent: Identity, school, health, activities

Examples

/jd:setup-system

Manage +SUB Index

Scan a +SUB category, update its index file, and optionally create new +SUB entries with the next sequential number.

Arguments

$ARGUMENTS may contain:

  • A system code (e.g., P10) and category number (e.g., 51) to target a specific +SUB category.
  • Just a system code to list all +SUB categories in that system.
  • No arguments to discover all +SUB categories across all systems.

Workflow

  1. Locate the target +SUB category and its index file.
  2. Scan existing +SUB folders (matching AC.ID+NNNN or AC.ID+CODE).
  3. Compare folder entries against the index file.
  4. Update the index with any missing entries.
  5. Report the current state: total entries, active/archived counts, next available number.

Creating New Entries

When the user wants to add a new +SUB entry:

  1. Determine the next identifier (sequential number or user-provided code).
  2. Create the +SUB folder.
  3. Update the index file.
  4. Update the JDex.

Examples

/jd:sub-index
/jd:sub-index P10
/jd:sub-index P10 51

Sponsors

Details

Marketplace
ngerakines/jd
Source
jd
Category
Community