juanandresgs/claude-ctrl/reckoning

/reckoning — Project Trajectory & Coherence Assessment

Analyze a project's MASTER_PLAN.md to understand the core of the project, the evolution of the idea, its development trajectory, whether the idea has evolved constructively or diverged from core intent, and produce an honest assessment in light of those findings.

Why this exists: The planner creates plans. The implementer follows them. The guardian protects them. Nobody evaluates whether the whole trajectory makes sense. The reckoning is the missing function — the project's honest self-exam. It tells you whether your project has a soul and whether that soul has been honored.

What this is NOT: A summary. Summaries are cheap. This is an analysis that draws connections the plan itself doesn't make explicit — between early decisions and late consequences, between stated principles and actual behavior, between non-goals and scope drift. The value is in what it reveals, not what it restates.

Phase 1: Locate, Ingest, and Orient

1a. Find the Plan

Parse $ARGUMENTS to determine the MASTER_PLAN.md location:

If the file doesn't exist or isn't a living-document format (no ## Identity section), stop and tell the user. Suggest invoking the planner if they need to create one.

1b. Read and Parse

Read the entire MASTER_PLAN.md. Extract and hold in working memory:

Stable DNA (rarely changes):

• Identity — what the project says it is
• Original Intent — the sacred text; the vision as first stated
• Principles — the enduring design values
• Architecture — the intended structure

Evolutionary Record (append-only):

• Decision Log — every significant decision, dated and rationalized
• Active Initiatives — current work with goals, non-goals, requirements, waves
• Completed Initiatives — compressed summaries of finished work
• Parked Issues — deferred work with rationale

Derived Counts:

• Total initiatives (active + completed)
• Total decisions in log
• Total parked issues
• Project age (Created date to today)

1c. Detect Maturity Tier

The analysis depth scales to the project's history:

State the detected tier and why. This frames the entire analysis — don't apply mature-project scrutiny to a project that's three days old.

Phase 2: Cross-Reference with Reality (Adaptive)

The plan tells the intended story. Reality may differ. Gather what's available — this phase is adaptive, not mandatory. Use what exists; note what doesn't.

2a. Git History (if in a git repo)

# Development timeline
git log --oneline --format="%h %ad %s" --date=short --since="[plan Created date]" | head -80
 
# Branch/merge history
git log --oneline --merges --since="[plan Created date]" | head -40
 
# Contributor pattern (if multi-author)
git shortlog -sn --since="[plan Created date]" | head -10

Map commits to initiatives and waves where possible. Note gaps (long periods without commits) and bursts (many commits in short windows).

2b. Codebase Structure (if code exists)

# Compare actual structure to Architecture section
ls -d */ 2>/dev/null | head -20
 
# Look for @decision annotations
grep -r "@decision DEC-" --include="*.sh" --include="*.md" --include="*.py" --include="*.ts" --include="*.js" -l 2>/dev/null | head -20

Compare actual directory layout against the Architecture section in the plan. Note discrepancies — directories that exist but aren't documented, documented directories that don't exist.

2c. GitHub Issues (if available)

# Check if GitHub remote exists
gh repo view --json name 2>/dev/null && \
  gh issue list --state all --limit 50 --json number,title,state,labels,createdAt 2>/dev/null

If issues exist, map them to plan wave items. Note:

• Plan items without corresponding issues (untracked work)
• Closed issues not reflected in the plan (undocumented completions)
• Open issues for completed initiatives (stale tracking)

2d. @decision Annotations in Code

If code exists, grep for @decision annotations and compare against the Decision Log:

• Decisions in code but not in the plan → undocumented decisions
• Decisions in the plan but not in code → unimplemented or unannotated
• DEC-ID mismatches → broken traceability

Note what you found and what you didn't. Missing cross-reference data is itself a finding ("this project has no @decision annotations in code despite 15 decisions in the plan — traceability is broken").

Phase 3: Seven-Dimensional Analysis

Apply each dimension sequentially. For each: gather evidence, draw connections, surface questions. Every claim must reference specific plan elements by section, DEC-ID, REQ-ID, or initiative name.

Dimension 1: Core Extraction

Question: What is this project fundamentally about?

Don't restate the Identity section. Distill. Read the Original Intent, the Principles, and the first initiative together — they form a triangle that reveals the project's soul. Then read the Decision Log chronologically — it shows what the project actually values through the choices it made.

Write 2-3 paragraphs capturing:

• The irreducible essence — what makes this project THIS project
• The founding tension — what problem demanded this project's existence
• The implicit philosophy — what beliefs about the domain are embedded in the design

Dimension 2: Chronological Reconstruction

Question: What happened, in what order, and at what pace?

Build a timeline from:

• Decision Log dates (primary — these are append-only and dated)
• Initiative start dates
• Completed Initiative periods
• Git history (if available from Phase 2)

Calculate and interpret:

• Decision density — decisions per time period. High early = strong vision or

rapid learning. Declining = stabilization or stagnation. Erratic = reactive development.

• Initiative velocity — how quickly initiatives progress through waves.

Stalled initiatives are a signal.

• Rhythm — steady cadence? Bursts of activity with long pauses? Accelerating?

Identify inflection points — moments where decision frequency, initiative scope, or project direction changed significantly. For each: what caused the shift? Was it reactive (something broke) or proactive (new insight)?

Dimension 3: Intent Alignment

Question: Has the work honored the Original Intent?

This is the most important dimension. Apply these specific tests:

1. Principle-Initiative Mapping: For each active and completed initiative,

which Principles does it serve? An initiative that serves no stated Principle is either scope drift or evidence that the Principles are incomplete.

1. Decision-Principle Alignment: Do architectural decisions reference

Principles in their rationale? They should — decisions grounded in Principles are more coherent than ad-hoc choices.

1. Non-Goal Migration: Scan non-goals across all initiatives. Has anything

declared as a Non-Goal in initiative A appeared as a Goal or requirement in initiative B? If so: was the original exclusion wrong (learning), or did scope creep smuggle it back in?

1. Language Drift: Compare the language used in the Original Intent with

language in recent initiatives. Semantic shift in how the project describes itself is a leading indicator of identity drift.

1. Original Intent Fulfillment: Is the Original Intent being actively

pursued, or has the project moved on to tangential concerns?

Produce a verdict: Strong | Moderate | Weak | Diverged With evidence for the rating.

Dimension 4: Decision Coherence

Question: Do the project's decisions form a consistent structure?

1. Internal Consistency: Do later decisions contradict earlier ones?

Contradictions aren't always bad — they can indicate learning — but they should be acknowledged and rationalized.

1. Decision Chains: Do decisions reference each other? A decision that says

"because of DEC-003, we chose..." shows historical awareness. Isolated decisions suggest fragmented thinking.

1. Rationale Quality: Are decision rationales substantive ("we chose X over Y

because of constraint Z, which matters more than benefit W") or performative ("this seemed like the best approach")?

1. Decision Gaps: Are there obvious choices that were made but never recorded?

Things that clearly changed in the project's direction without a corresponding DEC-ID.

1. Implementation Fidelity: (If Phase 2 found @decision annotations) Do code

decisions match plan decisions? Are there code-level decisions not in the plan?

Produce a verdict: Strong | Moderate | Fragmented

Dimension 5: Scope Evolution

Question: How have the project's boundaries moved?

Map how scope has changed across initiatives:

1. Expansions: Things added that weren't in the original vision. For each:

was this necessary learning (the original scope was too narrow) or undisciplined growth (we kept adding because we could)?

1. Contractions: Things dropped that were originally in scope. For each:

wise pruning (we learned it wasn't needed) or failure to execute (we couldn't get it working)?

1. Parked Issues Analysis: The Parked Issues section reveals what the project

considered but deferred. Assess:

• Are these genuinely deferred, or effectively abandoned?
• Do parked items accumulate faster than they're resolved?
• Is there a pattern to what gets parked? (Always the same type of work?)

1. P2 (Future Consideration) Tracking: Requirements marked P2 are promises

to a future self. Are prior P2 items showing up in later initiatives, or are they quietly abandoned?

Dimension 6: Project Health

Question: How healthy is this project as a living system?

Derive composite indicators from the evidence gathered:

Rate each: use the scale given in the output template. Provide specific evidence for each rating — never rate without justification.

Dimension 7: Trajectory

Question: Where is this project heading, and should it be heading there?

This is the synthesis layer. Using everything from Dimensions 1-6:

1. Current Vector: What direction is the project actually moving? Not what the

plan says — what the pattern of recent work reveals.

1. Projected Destination: If current patterns continue unchanged for 3-6 months,

what does this project become? Is that what the Original Intent envisioned?