mindit-trace

name

mindit-trace

description

Walk a design decision backward through its dependencies and forward through its consequences using the decision graph stored in .mindit/decisions/. Use this whenever the user asks "why did we decide X," "what does this depend on," "what depends on this," "show me the history of this decision," "what evidence was this based on," or wants to understand the chain of reasoning behind a current design state. Also trigger when the user is debating a change and wants to see what other decisions would be affected. Reads from the .mindit/decisions/ directory and produces a traceback artifact.

mindit-trace

The third of three meta skills. Run this when the question is "how did we get here, and what depends on this."

What this skill does

Reads the decision artifacts already stored in .mindit/decisions/ and walks the graph defined by depends_on references. Surfaces the chain of reasoning behind a current design state. Lets the team answer "why did we decide X" by looking at the actual artifacts produced when X was decided, including the evidence cited at the time.

This is what mindit's stateful, file-based architecture exists for. Layers-style pure-prose skills cannot do this; mindit can.

When to run this

• The user asks "why did we decide X," "what was the reasoning behind Y."
• The user is about to change a decision and wants to know what else depends on it.
• The user is onboarding a new team member and wants to walk them through how the design got to its current state.
• The user is doing a retrospective and wants to revisit the evidence that backed prior decisions.
• The user asks for a "decision history," "decision chain," or "decision lineage."

How to analyze

1. Locate the starting decision. The user names a decision by ID (e.g. clarity-20260311-checkout-cta) or by description ("the decision about the checkout CTA size"). If by description, search filenames and titles in .mindit/decisions/ to find the match. If multiple match, ask which one.

2. Walk backward (dependencies). Read the depends_on field of the starting artifact. For each dependency, load that artifact, read its depends_on, recurse. Stop when you reach artifacts with no further dependencies (root decisions) or when you have walked five levels deep, whichever comes first.

3. Walk forward (consequents). Grep the .mindit/decisions/ directory for artifacts whose depends_on includes the starting decision's ID. Recurse the same way.

4. Build the trace. Produce both:

   • A backward chain: this decision was made because of X, which was made because of Y, which was made because of Z.
   • A forward chain: this decision is referenced by A, which is referenced by B.

5. Surface the evidence chain. For each artifact in the trace, list the evidence entries. The team should be able to see at a glance: "this whole branch rests on a single 2025 user interview."

6. Surface the score drift. For each force that appears multiple times in the chain, show how the score has moved over time.

7. Write the trace artifact.

Rubric

Trace does not produce a 0–100 score. The artifact's score field is set to -1.

Output format

Two files in .mindit/decisions/. Filename: trace-<yyyymmdd>-<slug>.{md,json}.

JSON conforms to schemas/decision.schema.json with skill: "mindit-trace", force: "meta", score: -1. The findings array contains one entry per linked decision, with severity set to "info" unless the trace surfaces a problem (orphan dependency, conflicting forces, stale evidence chain).

Markdown template

# Decision trace: <starting decision ID>

**Date:** <ISO date>
**Starting decision:** <ID and title>

## Backward chain (dependencies)
- <ID>: <title>
  - depends on <ID>: <title>
    - depends on <ID>: <title> [root]

## Forward chain (consequents)
- <ID>: <title> depends on this
  - <ID>: <title> depends on that

## Evidence chain
- <evidence entry from root>: <source>, confidence <level>
- <evidence entry from intermediate>: <source>, confidence <level>

## Score drift
For force <name>, scores over time:
- <date>: <score>
- <date>: <score>

## Findings
- <orphan dependency, if any>
- <stale evidence, if any>
- <conflicting force scores in the chain, if any>

## Summary
<one paragraph: what this trace tells us about the current state>

Example

User asks: "Why is our pricing page using three tiers instead of four?"

Trace starts at consequence-20260214-pricing-tier-count, score 67, summary "Decided three tiers based on funnel analysis."

Backward chain:

• consequence-20260214-pricing-tier-count depends on
  • confidence-20260208-pricing-research, score 71, summary "Five-customer interviews suggest decision paralysis at four tiers."
    • depends on clarity-20260120-pricing-baseline, score 54, summary "Current four-tier page scored low on clarity; users could not distinguish enterprise from premium."

Forward chain:

• consequence-20260214-pricing-tier-count is depended on by
  • cost-20260220-tier-engineering, score 80, "Three tiers reduces backend complexity by removing the role-based provisioning."
  • correctability-20260225-pricing-launch, score 41, "Three-tier change rolled out 100 percent on launch day with no telemetry."

Evidence chain:

• 5-customer interview, January 2026 (medium confidence)
• Funnel analytics, last 90 days (high confidence)
• One competitive analysis, dated November 2025 (low confidence)

Score drift on consequence force: 67 → no change yet (decision is recent).

Findings:

• Most of this branch rests on a single five-customer interview. Severity medium.
• Downstream correctability-20260225-pricing-launch scored 41 but did not flow back into the original consequence decision. Severity medium.

Summary: the three-tier decision is recent and based on thin evidence. Worth re-validating once the live tier-pick funnel has 30 days of data.

What this skill does NOT do

• Does not invent decisions that do not exist in .mindit/decisions/. If the directory is empty, say so and suggest the user run other mindit skills to populate it.
• Does not infer dependencies. It reads them from the depends_on arrays the other skills produced. The graph is only as good as the artifacts written.
• Does not edit prior decisions. It reads them. To revise a prior decision, run the relevant skill again and let the new artifact reference the old one.