user-instructions-tracker

name	user-instructions-tracker
description	Use for creating or updating `user-instructions.md` in each repository to track user directives, implementation status, owners, evidence, and last-updated timestamps with a deterministic workflow.

User Instructions Tracker

Quick Index (Action-Routed)

Read First (All Actions)

1. Mission
2. Trigger Rule (Required)
3. Canonical Artifact
4. Required Schema
5. Status Model (Required)

Action Modules (Read As Needed)

1. Adding/updating directives:
   • Instruction ID Rules
   • Update Workflow
2. Historical bootstrap:
   • Backfill Rule
3. Compliance checking:
   • Quality Gates
   • Minimal Timestamp Standard
4. Cross-doc synchronization:
   • Sync Requirements

Output

1. Output Contract
2. Anti-Patterns

Mission

Maintain a durable, auditable record of user-provided instructions and their fulfillment state inside each repository.

Trigger Rule (Required)

Use this skill when:

1. a repository has no user-instructions.md
2. user gives a new directive, constraint, or policy
3. instruction status changes (pending, in_progress, blocked, done, won_t_do)
4. user asks for progress, fulfillment, or instruction audit
5. scope/priorities change and instruction mapping must be updated

Canonical Artifact

Required file:

1. user-instructions.md at repository root

If missing:

1. create it before substantive implementation work continues (except emergency fix paths)

Required Schema

The file must contain:

1. title: # User Instructions Tracker
2. a status model section
3. a tracker table with exact columns:
   • Instruction ID
   • Instruction
   • Source
   • Status
   • Priority
   • Owner
   • Last Updated UTC
   • Evidence
   • Notes

Status Model (Required)

Allowed status values:

1. pending
2. in_progress
3. blocked
4. done
5. won_t_do

Rules:

1. every row must use one allowed value
2. done requires evidence
3. blocked requires blocker detail in notes
4. won_t_do requires rationale in notes

Instruction ID Rules

1. format: INST-### (zero-padded)
2. unique and stable across file history
3. never reuse IDs
4. superseded instructions keep original row and link successor in notes

Update Workflow

Step 1: Intake

1. add a new row for each materially distinct user directive
2. keep instruction text concise but faithful to user intent
3. include source reference (date/turn summary)

Step 2: Plan Linkage

1. mark pending or in_progress
2. assign owner (model, user, or specific role)
3. set priority (high, medium, low)

Step 3: Execution Linkage

1. update status as work progresses
2. attach concrete evidence:
   • file references
   • artifact IDs
   • validation command summaries

Step 4: Closure

1. set done only when acceptance condition is satisfied
2. update Last Updated UTC on every status transition
3. add brief closure note

Backfill Rule

When introducing tracker to an existing repo:

1. add INST-000 backfill task row
2. summarize key historical instructions at high level
3. avoid fabricated certainty; mark unknowns explicitly

Quality Gates

Tracker is non-compliant if:

1. required table columns missing
2. duplicate instruction IDs exist
3. status value outside allowed set
4. done row has empty evidence
5. blocked/won_t_do row has empty notes
6. missing or invalid Last Updated UTC

Minimal Timestamp Standard

1. use ISO-8601 UTC (example: 2026-05-13T06:10:00Z)
2. update timestamp whenever status, evidence, or notes change

Sync Requirements

Keep tracker synchronized with:

1. AGENTS.md default behavior/policy changes
2. governance artifacts (docs/governance/*.governance.*) when task-level directives are involved
3. docs that declare process constraints (README.md, docs/*.md)
4. docs/skill-index.md when user directives change cross-skill trigger behavior

Output Contract

When applying this skill, provide:

1. rows added/updated
2. status transitions made
3. evidence links recorded
4. unresolved blocked/won_t_do items

Anti-Patterns

1. marking done without evidence
2. overwriting old rows instead of appending/updating status
3. using vague notes with no actionable blocker/rationale
4. letting tracker drift from actual implementation state
5. storing instruction state only in chat and not in repo artifact

Related Skills

• Doc Maintenance: ensures tracker updates are part of completion.
• File Maintenance: improves long-horizon tracker factuality and stale-row cleanup quality.
• Skill Governance: aligns instruction state with task governance artifacts.
• Order of Operations: ensures tracker intake happens before major execution.
• Token Reduction: keeps tracker entries concise and high-signal.