approval-console
Skill2 starsChanged 4 months agoApache-2.0View on GitHub
Package a raised judgment call into a reviewable decision package, then record a named human's answer into the committed readiness artifacts. Use for sign-off packaging or recording a decision. It only transcribes a decision a human supplied.
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-evidence-packSkill
- business-knowledge-interviewSkill
- capabilitiesSkill
- consumer-data-dictionarySkill
- cross-table-lineageSkill
- dagster-orchestration-adapterSkill
- dashboard-designSkill
- dashboard-intelligenceSkill
- dbt-transformation-adapterSkill
- evidence-pack-generatorSkill
- first-hour-compassSkill
- friendly-pr-reviewerSkill
- grain-confidence-reviewerSkill
- kpi-contract-builderSkill
- pbi-mcp-write-adapterSkill
- pbip-workflowSkill
- pbip-xraySkill
- pbir-authoring-adapterSkill
- portfolio-watchSkill
- powerbi-dashboard-designSkill
- pr-readiness-reviewerSkill
- readiness-viewerSkill
- release-notes-generatorSkill
- report-intent-interviewSkill
- retail-build-warehouseSkill
- retail-control-roomSkill
- retail-discover-portfolioSkill
- retail-governSkill
- retail-initSkill
- retail-onboard-tableSkill
- retail-orchestrateSkill
- retail-scaffoldSkill
- retail-semantic-checkSkill
- retail-validateSkill
- run-next-readinessSkill
- seshat-studioSkill
- showcase-buildSkill
- source-mappingSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- bi-analyst-knowledgeSkill
- bi-bigdata-knowledgeSkill
- bi-dax-knowledgeSkill
- bi-python-knowledgeSkill
- bi-sql-knowledgeSkill
- retail-kpi-knowledgeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 7 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 77
ONLY when gated (see below), a stage status flipped to pass.
- Distinctive: line 79
Every written cell is a TRANSCRIPTION of the human's answer or a copy of a committed source path -- it is DERIVED evidence, never a new …
- Very specific: line 92
MUST NOT pick selected_option, supply/forge owner, or invent rationale (no deciding).
- Very specific: line 93
MUST NOT auto-accept recommended_default -- an accepted default is an explicit named-owner decision.
- Very specific: line 94
MUST NOT move a readiness stage to pass without the stage's required evidence AND a named human approval.
- Distinctive: line 95
MUST NOT record a decision under an authority class that does not match the question class.
- Distinctive: line 96
MUST NOT silently overwrite a prior recorded approval -- it surfaces the conflict.
- Distinctive: line 97
MUST NOT create truth: no defining business meaning, no approving a metric/mapping (Core Authority / named human only).
- Distinctive: line 98
MUST NOT connect to a DB / external service, and MUST NOT publish a Power BI artifact (that is an Execution Adapter).
- Distinctive: line 99
MUST NOT emit a numeric / maturity / confidence score (hard rule #9).
- Very specific: line 100
MUST NOT add a seshat check rule, a CLI verb, or Python.
- Very specific: line 104
When a required Core Authority input is absent (no human answer, a missing write-back target, missing stage evidence, a phantom …
- Very specific: line 139
Serialization (verbatim per target): When the decision is written back, the console records the DECIDER, not just the authority class, so …
- Very specific: line 180
If a target artifact is MISSING or unwritable, record the decision with a remaining_blockers entry naming the missing target and do NOT …
- Distinctive: line 211
If asked to "score this decision's confidence" or "give a readiness number", DECLINE: cite the readiness-model "No fake confidence" rule …
- Very specific: line 249
When tables are driven end-to-end, the retail-orchestrate conductor may invoke the console when a raised judgment call BLOCKS the next …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
approval-console
- Roadmap feature: F027. On-disk spec:
specs/021-approval-console/. When the spec-dir number (021) and the roadmap F-number (F027) disagree, the roadmap F-number wins: this is F027.
The kit STOPS at judgment calls (Principle V) and the readiness spine RESERVES the slot
for the answer (readiness-status.yaml approvals[]; the unresolved-questions.md
Open-questions Resolution column). What it lacks is the LOOP between "a question was
raised" and "the named human's answer is recorded in the committed artifacts". This skill
is that loop, and only that loop. It does two things: (1) packages a raised judgment call
into a reviewable DECISION PACKAGE (a request), and (2) once a named human answers,
RECORDS that decision back into the committed artifacts. An approval that lives only in
chat is not an approval -- it cannot be reviewed, advance a gate, or be audited.
Authority declaration (F024 module contract -- filled)
- Authority category: Product Module
- Capability level:
artifact-writing(exactly one) - Product layer: 1-6 (all stages -- the functional axis; orthogonal to category)
- Roadmap feature: F027 On-disk spec:
specs/021-approval-console/ - Owner: the named human who decides each judgment call (the console transcribes; it is never the owner)
- Status: Authored (skill + two templates + one docs page; no runtime code)
What it does (one line)
Consumes a raised judgment call + a named human's answer, and WRITES the transcribed decision through to the committed
unresolved-questions.mdResolution + thereadiness-status.yamlapprovals[]slot -- it never authors the decision itself.
Project-scoped target: provisioning approvals (spec 154 / #671)
Most approvals this console transcribes are PER-TABLE, into
mappings/<table>/readiness-status.yaml approvals[]. One is PER-PROJECT:
authorizing the installation of external software.
- Target:
contracts/provisioning-approvals.yaml-- never a per-table readiness record. Provisioning authority is about the project's environment and tooling, not one table's readiness, and the gate refuses a provisioning approval found under amappings/<table>/path. - Row shape:
stage: provisioning,owner: "<Person Name> (governance)",at: <YYYY-MM-DD>,components: [<ids>], optionalnote, optionalrevoked: true. - Authority class is
governanceonly -- the named human project-governance authority for external environment/tool changes. A shape-validanalystordata_ownerrow is refused. - The decision must be COMMITTED.
seshat integrations setup --applyreads the file at HEAD, so an uncommitted transcription authorizes nothing -- which is the protection: the party requesting the install cannot also supply the permission.
Everything else about this skill's posture is unchanged: it transcribes a decision
a named human supplied and never authors one. The provisioning gate
(seshat.integrations.approval) only ever READS, so it cannot become a second
write path.
Core Authority it READS
mappings/<table>/unresolved-questions.md-- the Open-questions row a request packages (the question, why it blocks, the "Who must answer" authority class, the proposed default).mappings/<table>/readiness-status.yaml-- per-stagestatus, the stage's recordedevidence[], the existingapprovals[]entries (to detect a contradicting prior approval).- the surfacing features' evidence: a grain-confidence stop (F008), an open blocker the control room lists (F012), a metric contract's open question (F009) -- the inputs to a request.
Derived evidence it WRITES
templates/approval-request.md(filled) -- the decision package; poses a decision, never answers it.templates/approval-decision.md(filled) -- the transcribed human answer (written FIRST, the durable record).mappings/<table>/unresolved-questions.md-- the matching row'sResolutioncell +Statusflippedopen->answered.mappings/<table>/readiness-status.yaml-- anapprovals[]entry (stage+owner+at); and, ONLY when gated (see below), a stagestatusflipped topass.
Every written cell is a TRANSCRIPTION of the human's answer or a copy of a committed source path -- it is DERIVED evidence, never a new approval the console authored and never a new metric/mapping definition.
Approved step it EXECUTES
- none. This is an
artifact-writingmodule, notexecution-capable. Thepass-flip is a GATED WRITE of transcribed evidence (theapprovals[]entry + the stagestatusfield), not an execution-capable local step. The console opens no DB connection, runs no validator, and publishes nothing.
Forbidden operations (the matrix says NO)
- MUST NOT pick
selected_option, supply/forgeowner, or inventrationale(no deciding). - MUST NOT auto-accept
recommended_default-- an accepted default is an explicit named-owner decision. - MUST NOT move a readiness stage to
passwithout the stage's required evidence AND a named human approval. - MUST NOT record a decision under an authority class that does not match the question class.
- MUST NOT silently overwrite a prior recorded approval -- it surfaces the conflict.
- MUST NOT create truth: no defining business meaning, no approving a metric/mapping (Core Authority / named human only).
- MUST NOT connect to a DB / external service, and MUST NOT publish a Power BI artifact (that is an Execution Adapter).
- MUST NOT emit a numeric / maturity / confidence score (hard rule #9).
- MUST NOT add a
seshat checkrule, a CLI verb, or Python.
How it handles a missing input
When a required Core Authority input is absent (no human answer, a missing write-back
target, missing stage evidence, a phantom question_id, a duplicate question_id), the
console SURFACES it as a blocker and stops -- it never fabricates the input, self-approves,
or proceeds past the missing gate (Principle V; stop-and-ask). See the procedure below.
The transcribe-never-author boundary (read first)
The console TRANSCRIBES a human decision and WRITES it into the committed artifacts; it does NOT pick the option, supply or forge the owner, invent the rationale, auto-accept a recommended default, or move a readiness stage to
passwithout the stage's required evidence AND a named human approval. The named human decides; the console records. If no human answer exists, there is nothing to record and the request stays open.
This is the single load-bearing rule. A module that WRITES into Core-Authority artifacts is
exactly where an agent is tempted to self-approve or upgrade a stage; both are forbidden and
hard-stop. The console is the EXECUTOR of an already-made decision, not a discretionary
approver (the architectural Core-Authority rule; docs/architecture/product-modules.md).
Readiness vocabulary (fixed; no score)
The four statuses ONLY: not_started | blocked | warning | pass, plus evidence[]
blocking_reasons[]. There is NO numeric / health / confidence score field anywhere (hard rule #9). Apassis the named-owner approval recorded as evidence (owner + date), never a number. A stage flips topassONLY when BOTH a named human approval AND the stage's required evidence already exist (thepass-flip rule).
The four authority classes (the decider must match the question)
- analyst -- business meaning / grain / rollups
- governance -- PII / publish-safety sign-off
- data-owner -- source semantics / upstream truth
- metric-owner -- metric contracts (an ADDITIVE extension class from F009 metric
contracts; NOT present in the base
unresolved-questions.mdtemplate -- used ONLY for a metric-contract question; documented as not-yet-present indocs/tools/approval-console.md)
Serialization (verbatim per target). When the decision is written back, the console
records the DECIDER, not just the authority class, so the named-human guarantee is
auditable from committed evidence (audit C4): readiness-status.yaml approvals[].owner
holds the person's NAME followed by the authority class in parentheses --
"<Person Name> (<analyst | governance | data_owner | metric_owner>)" (e.g.
"Ahmed Shaaban (data_owner)"). The unresolved-questions.md "Who must answer" cell keeps
the role token in that artifact's existing spelling (analyst / governance / data-owner),
and the matching Resolution records the person + date. A bare role token with no person in
approvals[].owner is a defect -- an approval must trace to a named human, never a role alone.
The procedure
1. Package a raised judgment call into a request (US1)
Render templates/approval-request.md from ONE open judgment call. Fill question_id
(matching the source row), stage, subject, decision_needed (one sentence), evidence
(measured numbers + the committed source path each was read from), options, impact (per
option), recommended_default (only if the source carries one traceable to a committed
source -- else omit; mark it NOT auto-accepted), owner_required (the question's authority
class), and artifacts_to_update_after_decision. Record NO selected_option -- a request
never answers itself. If a required number is not yet measured, record
evidence incomplete: <source> and do NOT invent it.
Duplicate guard. A question_id resolves to exactly ONE request. If the same
question_id is packaged twice, surface the duplicate as a remaining_blockers line on the
request side and DECLINE to create a second decidable request -- the one existing request is
authoritative (never create a second decidable copy).
2. Transcribe the named human's answer + write it through (US2)
On a named human's answer, render templates/approval-decision.md FIRST (the durable
record): selected_option, owner, date, rationale -- each TRANSCRIBED from the human,
none fabricated; a field the human did not supply is left unfilled. Then apply BOTH
write-throughs idempotently:
unresolved-questions.md: fill the matching row'sResolution(decision + date + owner) and flipStatusopen->answered.readiness-status.yaml: append anapprovals[]entry --stage+owner(the DECIDER by name + authority class, e.g.Ahmed Shaaban (data_owner); never a bare role token) +at(populated from the decision'sdate).
If a target artifact is MISSING or unwritable, record the decision with a
remaining_blockers entry naming the missing target and do NOT fabricate it or perform a
partial stage flip. A pass flip occurs ONLY after BOTH write-throughs land alongside the
stage's required evidence.
The pass-flip rule. Flip the stage status to pass ONLY when BOTH already exist: the
named human approval (this decision) AND the stage's own required evidence (e.g. the live
retail validate result for Gold Ready). Otherwise record the decision and leave the stage
unchanged, with the gap in remaining_blockers. The flip is mechanical -- the console
executes an already-made decision; it never grants one.
3. Refuse to decide; surface conflicts (US3)
- Asked to "just approve it" / pick the option / supply the owner / flip a stage to
passwithout a named human answer AND the required evidence: DECLINE, cite Principle V (stop-and-ask) and the Core-Authority rule, and return the open request unchanged (no artifact altered). - A decision recorded under the WRONG authority class (e.g. a PII publish-safety call recorded by an analyst, not governance): refuse to record it and NAME the required authority class.
- A new decision that CONTRADICTS a prior recorded
approvals[]entry: SURFACE the conflict as a finding; do NOT silently overwrite the prior approval. - An owner left blank: record owner
UNASSIGNEDand refuse to treat the decision as a valid approval; never self-assign the owner. - A decision for a question never packaged: require a matching request
question_id; do not record against a phantom question. - A stage already
pass: record a new decision as an AMENDMENT with its ownapprovals[]entry and surface it for review -- never a silent re-pass.
No fake confidence (the guardrail)
If asked to "score this decision's confidence" or "give a readiness number", DECLINE: cite the readiness-model "No fake confidence" rule (hard rule #9) and return the four explicit statuses + the recorded evidence + blockers with their source paths instead. A numeric score is OPTIONAL and DEFERRED; the console MUST NOT emit one.
Honest-state rules (never invent, never silently re-run)
| Situation | What the console does |
| Answer lives only in chat | treats the approval as NOT recorded; the request stays open until the write-back lands |
| A write-back target is missing/unwritable | records the decision, names the missing target in remaining_blockers, performs NO partial pass flip |
| Stage evidence absent (approval present) | refuses the pass flip, lists the missing evidence as a remaining blocker |
Same question_id packaged twice | surfaces the duplicate as a remaining_blockers line, declines a second decidable request |
| Decision under the wrong authority class | refuses to record it, names the required class |
| New decision contradicts a prior approval | surfaces the conflict as a finding; does NOT overwrite |
| Owner left blank | records UNASSIGNED, not a valid approval; never self-assigns |
| recommended_default with no traceable source | omits the default rather than inventing one |
See also
- The output shapes:
templates/approval-request.md,templates/approval-decision.md. - The operator guide + the boundary:
docs/tools/approval-console.md. - The slot this fills:
templates/readiness-status.yaml(approvals[]: stage / owner / at) andtemplates/unresolved-questions.md(Open-questions table + Resolution column). - The model + no-fake-confidence rule:
docs/readiness/readiness-model.md; the stage sequence:docs/readiness/readiness-pipeline.md. - The features that produce request inputs: F006 (onboarding), F008 (grain confidence), F012 (control room), F009 (metric contracts).
- The category it realizes:
docs/architecture/product-modules.md(F024; Product Module /artifact-writing) and the Core-vs-Module authority boundary (docs/architecture/core-vs-modules-and-adapters.md); the copy-me declaration:templates/module-contract.md. A filled instance is cited underdocs/worked-examples/. - The constitution: Principle V (stop-and-ask), VII (generic), VIII (static-first), IX (ASCII / no BOM).
Orchestration
When tables are driven end-to-end, the retail-orchestrate conductor may invoke the console
when a raised judgment call BLOCKS the next stage: the console packages the request, and --
once a named human answers -- records the decision and reports. It does NOT advance any stage
beyond the mechanical pass flip of an already-approved, already-evidenced step (the
pass-flip rule). The decision itself stays a named-human action; the conductor routes to
the console, the console transcribes, and the named human decides -- never the conductor and
never the console (.claude/skills/retail-orchestrate/SKILL.md).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

