24  Reproducible Threads workflow

24.1 Objective

Capture a Foundry Threads chat session history and preserve outputs in a reviewable, auditable repo on a local machine.

24.2 Prerequisites

Complete these first:

  • fnd-getting-started.qmd
    • login
    • create a Project
    • tagging for discovery
    • groups/permissions
    • any required platform conventions

You should also already have a GitHub analysis repo created from this template repo:

  • repo-create-generic-python-repo.qmd

Important: This workflow assumes your analysis repo was created from the template MVR-GIS/repo-generic-python, which includes the tooling used below: - python -m tools.foundry_threads

24.3 What is a “reproducible Threads session” in this context?

A reproducible Threads session should leave an audit trail that includes:

  • who/what: analyst, date/time window, project context
  • inputs: the prompt(s), any system/context constraints, and referenced datasets
  • configuration: model/tool settings as allowed by your environment
  • outputs: generated text, extracted entities/tables, files produced
  • provenance: dataset RIDs/paths (or equivalent identifiers), code version/commit, and run identifier

Your goal is that a reviewer can answer:

  • “What question was asked?”
  • “What data and code were used?”
  • “What did the assistant produce?”
  • “Where are the saved artifacts?”

24.4 Key idea: save often (platforms glitch)

Assume export mechanisms and UIs occasionally fail or “lose” context. The safe pattern is:

  • export the chat often
  • re-run the extractor often
  • commit at reasonable milestones (and/or end of day)

24.5 Where artifacts live in the repository

This workflow stores session artifacts under a platform-agnostic development folder:

  • dev/
    • sessions/
      • YYYY-MM-DD[_topic].md
      • .raw/
        • YYYY-MM-DD[_topic].threads_export.json
      • .backups/

Notes:

  • The primary human-readable record is the session markdown file:
    • dev/sessions/YYYY-MM-DD[_topic].md
  • The tool inserts structured metadata as YAML front matter at the top of the .md file (instead of writing a separate metadata.yml file).
  • The raw export JSON is preserved in:
    • dev/sessions/.raw/
  • Backups are written to:
    • dev/sessions/.backups/
    • These are meant to prevent loss during active work and are typically not committed to avoid repo bloat.

24.6 Step-by-step

Step 1 — Open your repo on your local computer

  1. Use VS Code installed on your computer.
  2. Open your repo.

Step 2 — Export the Threads chat session to JSON

In Foundry Threads:

  1. Perform you chat session.
  2. Use the Threads UI export/save option.
  3. Export the chat in JSON format.
  4. Save the export as:
  • threads_export.json
  • a local downloads file

Step 3 — Run the extractor (creates/updates the auditable artifacts)

In your local VS Code repo:

  1. Ensure the repo environment is available (per your platform’s Python environment conventions).
  2. From the repo root, run:
python -m tools.foundry_threads

This will:

  • write/update the session transcript:
    • dev/sessions/YYYY-MM-DD.md
  • write/update the raw export copy:
    • dev/sessions/.raw/YYYY-MM-DD.threads_export.json
  • if you re-run and a transcript already exists, create a backup:
    • dev/sessions/.backups/YYYY-MM-DD_backup_<timestamp>.md

Step 5 — Multi-topic days (optional)

If you have multiple distinct sessions/topics in the same day, add --topic:

python -m tools.foundry_threads --topic data_validation

This produces:

  • dev/sessions/YYYY-MM-DD_data_validation.md
  • dev/sessions/.raw/YYYY-MM-DD_data_validation.threads_export.json

Step 6 — Preserve the audit trail

In your repo commit the updated files. Minimum expected committed artifacts:

  • dev/sessions/YYYY-MM-DD*.md
  • dev/sessions/.raw/*.threads_export.json

Notes:

  • The .md file is what most reviewers will read.
  • The .raw JSON is preserved for audit integrity and re-derivation.
  • dev/sessions/.backups/ is typically not committed (local scratch safety).

Commit message guidance:

  • include date and a short purpose
  • example: Update Threads session log (2026-05-03)

24.7 Definition of done

You are done when:

  • the session transcript exists in-repo:
    • dev/sessions/YYYY-MM-DD[_topic].md
  • the raw export is preserved in-repo:
    • dev/sessions/.raw/YYYY-MM-DD[_topic].threads_export.json
  • the transcript includes YAML front matter metadata (title/date/user/model/hash)
  • the files are committed so a reviewer can retrieve them later