# Modeler Decision Logger

> Collect, stamp, and freeze the human modeler's decisions into one canonical per-subquestion decision log. The decision version of frozen_numbers.json — it does NOT originate decisions, it makes the human's judgments traceable, append-only, and the single source every downstream narrative is transcribed from.

- **Type:** Skill
- **Install:** `agentstack add skill-zhnnky329-mathmodeling-skills-modeler-decision-logger`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zhnnky329](https://agentstack.voostack.com/s/zhnnky329)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zhnnky329](https://github.com/zhnnky329)
- **Source:** https://github.com/zhnnky329/MathModeling-skills/tree/main/.codex/skills/modeler-decision-logger

## Install

```sh
agentstack add skill-zhnnky329-mathmodeling-skills-modeler-decision-logger
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Purpose

Maintain one canonical, append-only log of the human modeler's decisions, so that every modeling judgment a contest grades — which method and why, whether a result is good, what a number means, how confident the team is — has a single traceable home, and every downstream narrative (final method explanation, solution package, paper method-selection prose) is **transcribed from it, never re-invented**.

This is the decision-side parallel of the Frozen Numbers Convention. Just as `frozen_numbers.json` pins numbers so a bug fix can't silently shift the paper, the decision log pins judgments so the AI can't silently author what a judge grades, and so four different skills can't each re-compose the method-selection story and drift apart.

**This skill does NOT make decisions.** It never fills `modeler_decision` or `modeler_rationale`. It collects the human-authored decision artifacts that judgment-bearing skills emit (`methods/Qx/decisions/_modeler_decision.md`), validates them mechanically, stamps them, and folds them into the canonical log. It pre-fills only the mechanical fields (`decision_id`, `options_considered`, `evidence`, `ai_suggestion`).

# When to use

Use this skill:

- After a judgment-bearing skill (`method-selector`; later `result-report-generator`, `robustness-checker`, `final-method-explainer`, `solution-package-builder`) has captured a human decision in its `*_modeler_decision.md` artifact, to fold it into the canonical log.
- As a precondition check at Gates G2.5 / G4.5 / G5: "does the log contain a `DECIDED` record for the required decision point of this Qx?"
- When `final-method-explainer` / `solution-package-builder` / `paper-section-writer` need the method-selection narrative — they read it FROM this log with `decision_id` provenance, they do not re-author it.
- After the contest, to render the decision log as post-mortem review material.

Do NOT use this skill:

- To author, suggest, or auto-fill any human decision or rationale.
- To decide which method is right, what a number means, or whether a result is good.
- To overwrite a past decision (the log is append-only; a changed mind appends with `supersedes`).

# Preconditions

- At least one `methods/Qx/decisions/_modeler_decision.md` artifact exists with `status: DECIDED`.
- The Human Decision Artifact Convention in CLAUDE.md is the schema of record.

If a decision artifact is still `PENDING` (the human hasn't decided yet), do not log it — report it as "decision pending" and let the gate stay blocked.

# Inputs

- `methods/Qx/decisions/*_modeler_decision.md` — the per-skill human decision artifacts.
- The candidate pool / experiment reports the decision references (for `evidence` provenance).
- The existing `methods/Qx/qx_decision_log.md`, if any (to append to).
- `planning/session_config.json` (for `mode`, recorded per record).

# Workflow

1. Locate decided artifacts.
   - For the target Qx, find every `methods/Qx/decisions/_modeler_decision.md` with `status: DECIDED`.
   - Skip `PENDING` ones; report them as still-blocking.

2. Validate each decided artifact mechanically (do NOT re-judge the content).
   - `decided_by: human`; no sentinel survives in mandatory fields; over char floor.
   - Rationale is not a near-verbatim copy of `ai_suggestion` (normalized-whitespace / tiny edit distance only — fuzzy similarity is a ledger WARN, not a reject; formulas and `symbol_table.md` symbols are exempt).
   - Rationale references at least one concrete token from `evidence_refs`.
   - If validation fails, do NOT log it — return it to the gate as a FAIL with the exact reason.

3. Append to the canonical log.
   - Write one decision record per validated artifact into `methods/Qx/qx_decision_log.md`.
   - Stamp `decision_id` (monotonic `Qx-D01`, `Qx-D02`, …), `decision_point` (from the fixed taxonomy below), `timestamp`, and `captured_in_mode`.
   - **Append-only.** If this decision revises an earlier one, set `supersedes: ` and append a new record; never edit the prior record.

4. Update the global index.
   - Maintain `planning/decision_log_index.md`: one row per decision across all Qx (id, Qx, decision_point, choice, confidence, supersedes).

5. Provide the narrative source for downstream skills.
   - When asked for the method-selection narrative, return the relevant `modeler_rationale` fields verbatim/near-verbatim, each tagged with its `decision_id`, so the consuming skill can cite provenance (``).
   - The AI consuming this is forbidden from writing a method-justification sentence that has no backing decision record.

6. Staleness check (mirrors frozen_numbers).
   - If a `code/Qx/*` change shifted a result that a `result_verdict` record was based on, mark that record `STALE — modeler must re-confirm verdict against new result`. Do not silently keep a verdict the human signed against now-changed numbers.

# Decision-point taxonomy (fixed)

A record's `decision_point` is exactly one of:
`framing` · `method_choice` · `assumption_necessity` · `baseline` · `hyperparameter` · `result_verdict` · `confidence` · `claim_scope` · `figure_role`

The four a judge actually grades are **mandatory** before "Ready for Writer": `method_choice`, `result_verdict`, `confidence`, `assumption_necessity`. The rest are optional. `completeness-auditor` checks the mandatory four exist per Qx.

# Outputs

- `methods/Qx/qx_decision_log.md` — the canonical append-only log for Qx.
- `planning/decision_log_index.md` — global roll-up across all Qx.

# Output format

`methods/Qx/qx_decision_log.md`:

```markdown
# Qx Decision Log

> Canonical, append-only record of the modeler's decisions for Qx.
> Downstream narratives transcribe from here with `decision_id` provenance. Never edited in place.

---

### Q2-D01 · method_choice · 2026-06-06T14:20+08:00 · mode: learning
- **options_considered**: M1 moving-average (baseline) / M2 ARIMA / M3 grey GM(1,1)   
- **evidence**: PoC feasibility — M2 RMSE 2.4 on first 50 months (methods/Q2/poc/m2_poc_result.txt) 
- **ai_suggestion**: M2 ARIMA — best PoC fit   
- **modeler_decision**: M2 (CHOSEN)            
- **modeler_rationale**:    
- **confidence**: medium
- **supersedes**: —

### Q2-D02 · result_verdict · 2026-06-07T09:10+08:00 · mode: speed
...
```

`planning/decision_log_index.md`:

```markdown
# Decision Log Index (all subquestions)

| id | Qx | decision_point | choice | confidence | supersedes |
|----|----|----------------|--------|------------|------------|
| Q2-D01 | Q2 | method_choice | M2 | medium | — |
| Q2-D02 | Q2 | result_verdict | M2 CHOSEN | high | — |
```

# Post-contest review

Because every record carries `options_considered`, `evidence`, the human's `modeler_decision` + `modeler_rationale`, and a `supersedes` chain, the index is a decision diary. After the contest it renders, per record: "At Q2-D01 you chose M2 over M3 because ; the evidence then was ." The `supersedes` chains show where the team's thinking changed — the most useful thing for a student to revisit. This is the learning payoff: the artifact that gated the contest is the study guide afterward, with zero extra authoring.

# Rules

- Never author, suggest, or auto-fill `modeler_decision` or `modeler_rationale`. Pre-fill only `decision_id` / `options_considered` / `evidence` / `ai_suggestion`.
- Never decide which method is right, what a number means, or whether a result is good.
- Append-only. Never edit or delete a past record. A changed mind is a new record with `supersedes`.
- Do not log a `PENDING` artifact. Do not log an artifact that fails mechanical validation — return it to the gate.
- Validation is mechanical only (existence / floor / sentinel / near-verbatim-copy / evidence-citation). Do not grade the modeling content.
- A downstream narrative sentence claiming "why we chose X" must trace to a `modeler_rationale` in this log. If the human hasn't logged the why, the paper may not assert the why.
- Keep the mandatory decision-point set minimal (the four graded ones) to avoid authoring burden; the rest are opt-in.

# Verification

Before handing off, verify:

- Every `DECIDED` artifact for this Qx is reflected as exactly one record.
- No `PENDING` artifact was logged.
- The mandatory decision points (`method_choice`, `result_verdict`, `confidence`, `assumption_necessity`) exist for any Qx marked Ready-for-Writer.
- The global index matches the per-Qx logs.
- No record was edited in place; revisions used `supersedes`.
- No human field was authored by this skill.

# Failure modes

Stop and report a blocker if:

- A required decision artifact is `PENDING` (the human hasn't decided) — the gate stays blocked; this is not an error, it's the design.
- A decision artifact fails mechanical validation (empty / sentinel / near-verbatim copy / no evidence citation) — return it to the modeler with the exact field.
- A downstream skill asks this logger to author a rationale — refuse.
- A `result_verdict` record is stale (its underlying number changed) — flag for re-confirmation, do not silently keep it.

# Handoff

- To `final-method-explainer` / `solution-package-builder` / `paper-section-writer`: provide the `modeler_rationale` fields with `decision_id` tags as the narrative source.
- To `workflow-orchestrator`: report which mandatory decision points are present vs missing per Qx (gate input).
- To `consistency-auditor`: the log is a cross-media source — every "why we chose X" sentence in the paper must trace to a `decision_id` here.

# Relationship to the conventions

This skill operationalizes the **Human Decision Artifact Convention** (CLAUDE.md) by giving the scattered per-skill decision artifacts one canonical, append-only home, with the same immutability discipline as the **Frozen Numbers Convention**: append-with-`supersedes` is the decision-side analogue of `解冻 → 修改 → 重冻结`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zhnnky329](https://github.com/zhnnky329)
- **Source:** [zhnnky329/MathModeling-skills](https://github.com/zhnnky329/MathModeling-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zhnnky329-mathmodeling-skills-modeler-decision-logger
- Seller: https://agentstack.voostack.com/s/zhnnky329
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.