s-note

name	s-note
description	Add a quick timestamped note to project decisions log - captures context without ceremony

/s:note - Quick Decision/Note Capture

Add a timestamped note to the project's decisions log in STATE.md. This is the lowest-ceremony way to capture a thought, decision, observation, or context that should persist across sessions.

Instructions

Step 1: Check for project initialization

Check if .planning/STATE.md exists.

If it does NOT exist:

• Display: "No project state found. Run /s:new to initialize a project first."
• Stop here.

Step 2: Get the note content

The note text can come from:

Option A - Argument provided: If the user invoked this skill with text (e.g., /s:note We decided to use PostgreSQL instead of MySQL), use that text directly as the note.

Option B - No argument: If no text was provided, ask the user: "What would you like to note?" and wait for their response.

Keep the barrier to entry as low as possible. One sentence is fine. A paragraph is fine. Do not require any specific format from the user.

Step 3: Determine the rationale

If the note text clearly implies a decision (contains words like "decided", "chose", "switching to", "going with", "will use", "agreed"), ask briefly: "Any rationale to record? (or press enter to skip)"

If the user provides rationale, capture it. If they skip or if the note is just an observation (not a decision), set rationale to "Quick note".

Do NOT over-ask. If the context is clear, infer the rationale. For example:

• "Switching to PostgreSQL for better JSON support" - rationale is embedded
• "Need to revisit auth flow" - this is an observation, rationale = "Quick note"

Step 4: Read current STATE.md

Read .planning/STATE.md to find the Decisions table. The table follows this format:

## Decisions
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-15 | Project created | - |

Step 5: Add the entry

Append a new row to the Decisions table in STATE.md:

| {YYYY-MM-DD} | {note text} | {rationale or "Quick note"} |

Rules for the entry:

• Date: Use today's date in YYYY-MM-DD format
• Decision: The note text, cleaned up if needed (capitalize first letter, no trailing period needed)
• Rationale: User-provided rationale, inferred rationale, or "Quick note"
• Preserve all existing table rows. Only APPEND. Never modify or delete previous entries.

Also update the Last Updated field in STATE.md to today's date.

Step 6: Confirm

Display a brief confirmation:

Note added to STATE.md decisions log.
  "{note text}" ({YYYY-MM-DD})

That is it. No further action needed.

Important Notes

• This skill should be FAST. Minimal questions, minimal output.
• The entire interaction should take seconds, not minutes.
• Do NOT restructure or reformat existing STATE.md content. Only append to the table.
• Do NOT suggest next actions. This is a quick capture tool, not a workflow step.
• If STATE.md exists but has no Decisions table, create the table with headers and then add the entry.
• Handle edge cases gracefully:
  • If the table format is slightly different, adapt rather than failing
  • If there are pipe characters in the note text, escape them or rephrase
  • If STATE.md is malformed, add the entry as best as possible
• Multiple notes can be added in sequence. Each /s:note call adds one entry.
• This skill pairs well with any other skill - use it anytime during a session to capture context that should survive across sessions.