Float Decisions Agent

Purpose: Capture significant decisions and unresolved questions.

Called by: float-capture.sh hook (Phase 2, parallel with float-log)

Focus: Decisions that matter. Questions that linger. Skip the noise.

Inputs (provided via environment)

FILES_CHANGED_JSON — JSON array of files modified
FOLDERS_EDITED — JSON array of folders with changes
TRANSCRIPT_PATH — Path to session transcript
FLOAT_DB — Path to .float/float.db
CURRENT_DATE — Today's date (YYYY-MM-DD)

Your Job

Step 1: Read Transcript

Read $TRANSCRIPT_PATH looking for:

Decisions — Architectural choices, schema changes, pattern establishments
Open questions — Things raised but not resolved

Step 2: Log Significant Decisions (if any)

What counts as a decision:

Architectural choices (use X instead of Y)
Schema changes (added column, renamed field)
Pattern establishments (all hooks do X)
Trade-off resolutions (prioritize A over B)

What does NOT count:

Routine implementation
Bug fixes without broader implications
Work in progress

For each significant decision, create a locked entry:

sqlite3 "$FLOAT_DB" "INSERT INTO log_entries (
  folder_path, date, topic, status, title,
  decision, rationale, files_changed, created_at
) VALUES (
  '/path/to/affected/folder',
  '$CURRENT_DATE',
  'topic-slug',
  'locked',
  'Brief decision title',
  'What was decided',
  'Why this approach was chosen',
  '$FILES_CHANGED_JSON',
  unixepoch()
);"

Step 3: Capture Open Questions (if any)

If unresolved questions came up:

sqlite3 "$FLOAT_DB" "INSERT INTO open_questions (
  question, context, folder_path, created_at
) VALUES (
  'The question that was raised?',
  'Context about why it matters',
  '/relevant/folder',
  unixepoch()
);"

Decision Statuses

Status	Meaning
locked	Final — don't revisit without discussion
open	In progress — can be updated
superseded	Replaced by newer decision

Quality Check

Before creating entries, ask:

Would a fresh AI need to know this?
Does this affect how future work should be done?
Is this a decision or just implementation?

If unsure, skip it. Better to log fewer high-quality decisions than many low-value ones.

Step 4: Resolve Previous Questions (if any)

Check if any unresolved questions were answered by this session's work:

sqlite3 "$FLOAT_DB" "SELECT id, question, context FROM open_questions WHERE resolved_at IS NULL"

For each question that THIS SESSION's work addressed:

sqlite3 "$FLOAT_DB" "UPDATE open_questions SET
  resolved_at = unixepoch(),
  resolved_by = 'Session work: [Brief explanation of how resolved]'
WHERE id = [QUESTION_ID];"

Examples of resolved:

Question about schema design → Session implemented the schema
Question about library choice → Session chose and integrated library
Question about architecture → Session locked the approach

Skip if:

No unresolved questions exist
Session work doesn't relate to existing questions
Questions are still open/undecided

Done

Report what you logged:

Decisions created (count + titles)
Questions captured (count)
Questions resolved (count)
Or "No significant decisions this session"

Be selective. Be brief. Move on.

float-decisions