AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

tc-tracker

Use when tracking technical changes as records, or handing work between AI sessions with a change record. Creates, updates and validates change records with tc_create.py, tc_update.py and tc_validator.py.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--tc-tracker at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 5

references/handoff-format.md

Session Handoff Format

The handoff block is the most important part of a TC for AI continuity. When a session expires, the next session reads this block to resume work cleanly without re-deriving context.

Where it lives

session_context.handoff inside tc_record.json.

Structure

{
  "progress_summary": "string",
  "next_steps": ["string", "..."],
  "blockers": ["string", "..."],
  "key_context": ["string", "..."],
  "files_in_progress": [
    {
      "path": "src/foo.py",
      "state": "editing|needs_review|partially_done|ready",
      "notes": "string|null"
    }
  ],
  "decisions_made": [
    {
      "decision": "string",
      "rationale": "string",
      "timestamp": "ISO 8601"
    }
  ]
}

Field-by-field rules

progress_summary (string)

A 1-3 sentence narrative of what has been done. Past tense. Concrete.

GOOD:

"Implemented JWT signing with HS256, wired the auth middleware into the main router, and added two passing unit tests for the happy path."

BAD:

"Working on auth." (too vague) "Wrote a bunch of code." (no specifics)

next_steps (array of strings)

Ordered list of remaining actions. Each step should be small enough to complete in 5-15 minutes. Use imperative mood.

GOOD:

  • "Add integration test for invalid token (401)"
  • "Update README with the new POST /login endpoint"
  • "Run pytest tests/auth/ and capture output as evidence T2"

BAD:

  • "Finish the feature" (not actionable)
  • "Make it better" (no measurable outcome)

blockers (array of strings)

Things preventing progress RIGHT NOW. If empty, the TC should not be in blocked status.

GOOD:

  • "Test fixtures for the user model do not exist; need to create tests/fixtures/user.py"
  • "Waiting for product to confirm whether refresh tokens are in scope (asked in #product channel)"

BAD:

  • "It's hard." (not a blocker)
  • "I'm tired." (not a blocker)

key_context (array of strings)

Critical decisions, gotchas, patterns, or constraints the next session MUST know. Things that took the current session significant effort to discover.

GOOD:

  • "The legacy_auth module is being phased out — do NOT extend it. New code goes in src/auth/."
  • "We use HS256 (not RS256) because the secret rotation tooling does not support asymmetric keys yet."
  • "There is a hidden import cycle if you import User from models.user instead of models. Always use from models import User."

BAD:

  • "Be careful." (not specific)
  • "There might be bugs." (not actionable)

files_in_progress (array of objects)

Files currently mid-edit or partially complete. Include the state so the next session knows whether to read, edit, or review.

| state | meaning | |-------|---------| | editing | Actively being modified, may not compile | | needs_review | Changes complete but unverified | | partially_done | Some functions done, others stubbed | | ready | Complete and tested |

decisions_made (array of objects)

Architectural decisions taken during the current session, with rationale and timestamp. These should also be promoted to a project-wide decision log when significant.

{
  "decision": "Use HS256 instead of RS256 for JWT signing",
  "rationale": "Secret rotation tooling does not support asymmetric keys; we accept the tradeoff because token lifetime is 15 minutes",
  "timestamp": "2026-04-05T14:32:00+00:00"
}

Handoff Lifecycle

When to write the handoff

  • At every natural milestone (feature complete, tests passing, EOD)
  • BEFORE the session is likely to expire
  • Whenever a blocker is hit
  • Whenever a non-obvious decision is made

How to write it (non-blocking)

Spawn a background subagent so the main agent doesn't pause:

"Read docs/TC/records/<TC-ID>/tc_record.json. Update the handoff section with: progress_summary='...'; add next_step '...'; add blocker '...'. Use tc_update.py so revision history is appended. Then update last_active and write atomically."

How the next session reads it

  1. Read docs/TC/tc_registry.json and find TCs with status in_progress or blocked.
  2. Read tc_record.json for each.
  3. Display the handoff block to the user.
  4. Ask: "Resume ? (y/n)"
  5. If yes:
    • Archive the previous session's current_session into session_history with an ended timestamp and a summary.
    • Create a new current_session for the new bot.
    • Append a revision: "Session resumed by <platform/model>".
    • Walk through next_steps in order.

Quality Bar

A handoff is "good" if a fresh AI session, with no other context, can pick up the work and make progress within 5 minutes of reading the record. If the next session has to ask "what was I doing?" or "what does this code do?", the previous handoff failed.

Anti-patterns

| Anti-pattern | Why it's bad | |--------------|--------------| | Empty handoff at session end | Defeats the entire purpose | | next_steps: ["continue"] | Not actionable | | Handoff written but never updated as work progresses | Goes stale within an hour | | Decisions buried in notes instead of decisions_made | Loses the rationale | | Files mid-edit but not listed in files_in_progress | Next session reads stale code | | Blockers in notes instead of blockers array | TC status cannot be set to blocked |