@gillcash/necktie 0.2.0 → 0.4.0

package/skills/necktie-critique/SKILL.md

@@ -1,48 +0,0 @@
----
-name: necktie-critique
-description: Critique and expand an inquiry before execution by testing goal alignment, assumptions, omitted perspectives, and evidence needs. Use inside the Necktie loop or when the user asks what they overlooked, wants the strongest unasked expert question, requests a red-team of the framing, or needs material follow-up questions rather than a direct answer.
----
-
-# Necktie Critique
-
-Critique the inquiry, not merely the current answer. Broaden the user's view without turning the task into an endless discovery interview.
-
-## Inputs
-
-Obtain the goal, intended audience, acceptance criteria, source ledger, constraints, and any baseline approach. If one is missing, infer it when safe and label the assumption.
-
-## Method
-
-1. Restate the actual decision or outcome in one sentence.
-2. Test whether the requested deliverable is a means to that outcome or has become the goal by accident.
-3. Check the baseline for hidden assumptions, missing stakeholders, incentives, failure modes, alternative explanations, data limitations, and implementation constraints.
-4. Identify contradictions between the goal, evidence, requested format, and available authority.
-5. Simulate the most relevant genuine subject-matter expert. Ask what that expert would need to know before trusting or acting on the result.
-6. Select the single strongest unasked question: the question whose answer would most change the plan, conclusion, or risk.
-7. Separate questions into:
-   - `material-now`: execution should pause because different answers produce meaningfully different outputs.
-   - `assumption-safe`: proceed under a clearly stated default.
-   - `optional-later`: useful but outside the current scope.
-8. Reframe the inquiry so it targets the user's outcome, includes the necessary controls, and remains answerable from the permitted sources.
-
-Do not invent domain facts, confuse method guidance with evidence, or criticize stylistic preferences that do not affect the goal.
-
-## Output
-
-Return this compact structure:
-
-```text
-Outcome test: ...
-What is missing or misframed:
-- ...
-Assumptions to expose:
-- ...
-Strongest unasked question: ...
-Why it matters: ...
-Material questions for the user:
-- ... (or "None; proceed with the stated assumptions.")
-Reframed inquiry: ...
-Readiness: READY | NEEDS-ANSWER | BLOCKED
-```
-
-Use `NEEDS-ANSWER` only for a material user choice. Use `BLOCKED` only when required evidence or authority cannot be obtained within scope.

package/skills/necktie-critique/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Necktie Critique"
-  short_description: "Challenge goals and surface blind spots"
-  default_prompt: "Use $necktie-critique to challenge this inquiry before execution."
-policy:
-  allow_implicit_invocation: false

package/skills/necktie-reverse/SKILL.md

@@ -1,41 +0,0 @@
----
-name: necktie-reverse
-description: Reverse-engineer an iterative conversation, critique, and successful refinements into one fresh-session executable brief. Use inside the Necktie loop, when the user asks for prompt reversal, when a sequence of revisions should become a reusable prompt, or when execution must be separated from prior answer leakage.
----
-
-# Necktie Reverse
-
-Compile the useful decisions from an iterative exchange into one self-contained brief that could have produced the desired result in a fresh session.
-
-## Build the brief
-
-1. Read [references/blueprint-template.md](references/blueprint-template.md) completely.
-2. Extract the stable goal, audience, constraints, approved refinements, source hierarchy, required deliverables, acceptance criteria, and verification requirements.
-3. Preserve explicit user choices. Resolve contradictions by favoring the latest explicit instruction, then higher-authority constraints, then the option best aligned with the stated goal.
-4. Incorporate critique findings that materially improve correctness, usefulness, risk control, or verifiability.
-5. Exclude conversational debris, abandoned approaches, praise, hidden reasoning, and claims that appeared only in prior outputs.
-6. Require fresh execution from raw sources. Label prior outputs as hypotheses or style references unless independently supported.
-7. Include a reviewer contract with an exact decision vocabulary and stopping rule.
-8. Make the brief specific enough to execute yet independent of a particular model, tool name, or unavailable session state.
-
-## Quality test
-
-Before returning the brief, verify that a capable agent in a new session could answer all of these from the brief alone:
-
-- What outcome matters, for whom, and why?
-- Which sources can prove claims, and which only guide the method?
-- What is in and out of scope?
-- What must be delivered and in what form?
-- What constitutes acceptance or failure?
-- What should be checked, by whom, and when should the loop stop?
-
-If a material answer is missing, ask one focused question or state a safe assumption. Do not smuggle unresolved ambiguity into vague language.
-
-## Output
-
-Return:
-
-1. `Executable brief` in a single copyable block using the template headings.
-2. `Compilation notes` listing only material assumptions, excluded prior-output claims, and unresolved limitations.
-
-Do not include a transcript summary or chain-of-thought.

package/skills/necktie-reverse/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Necktie Reverse"
-  short_description: "Compile iterations into an executable brief"
-  default_prompt: "Use $necktie-reverse to compile this goal and critique into one executable brief."
-policy:
-  allow_implicit_invocation: false

package/skills/necktie-reverse/references/blueprint-template.md

@@ -1,54 +0,0 @@
-# Executable brief template
-
-Use these headings. Omit a heading only when it is genuinely inapplicable.
-
-```text
-ROLE
-Act as [relevant role and perspective].
-
-OUTCOME
-Produce [artifact/action] so that [audience] can [real-world outcome].
-
-INPUTS AND SOURCE HIERARCHY
-- Evidence: [sources that may support claims]
-- Method guidance: [sources that govern the process only]
-- Constraints: [authority, safety, scope, format]
-- Prior outputs: [hypotheses/style references only]
-Resolve conflicts in this order: [explicit hierarchy].
-
-SCOPE
-Include: [...]
-Exclude: [...]
-
-MATERIAL ASSUMPTIONS
-- [...]
-
-WORKFLOW
-1. Inspect and classify sources.
-2. Establish a baseline and expose assumptions.
-3. Challenge the inquiry and identify the strongest unasked question.
-4. Produce the deliverable from raw evidence.
-5. Review against the acceptance criteria.
-6. Revise within the stated stopping rule.
-7. Verify in the target environment.
-
-DELIVERABLES
-- [exact output, format, and location]
-
-ACCEPTANCE CRITERIA
-- [observable pass/fail criterion]
-
-EVIDENCE AND CITATION RULES
-- [claim support, freshness, provenance, quotation, or uncertainty rules]
-
-REVIEW CONTRACT
-Return APPROVE, REVISE, or BLOCK. Report only material findings with exact evidence and the smallest required change. Ask the strongest unasked expert question. Do not rewrite while reviewing.
-
-STOPPING RULE
-Stop when all criteria pass, a material blocker requires user input, the same issue survives three reviews, or three revision decisions are recorded.
-
-HANDOFF
-Return the artifact, reusable brief, verification record, limitations, overlooked consideration, and strongest unasked question.
-```
-
-Write instructions that are observable and testable. Replace adjectives such as "excellent" or "comprehensive" with explicit criteria. Do not request hidden chain-of-thought; request concise assumptions, decisions, evidence, and verification instead.

package/skills/necktie-review/SKILL.md

@@ -1,61 +0,0 @@
----
-name: necktie-review
-description: Independently gate a candidate deliverable against its exact brief, evidence, acceptance criteria, and verification results. Use inside the Necktie loop, for an Auto-review-style approval decision, or when the user wants a concise APPROVE, REVISE, or BLOCK judgment with actionable material findings and a strongest unasked question.
----
-
-# Necktie Review
-
-Judge the proposed result without silently rewriting it or expanding its scope. Review as a separate role from the author, using the smallest evidence packet that permits a reliable decision.
-
-## Inputs
-
-Require:
-
-- the exact executable brief;
-- the candidate artifact or change set;
-- acceptance criteria and constraints;
-- a source ledger plus relevant evidence excerpts, paths, or links;
-- verification results, if already available.
-
-If an input is unavailable, decide whether that absence is itself a material finding. Read [references/reviewer-rubric.md](references/reviewer-rubric.md) completely before judging.
-
-## Review
-
-1. Inspect the candidate read-only. Do not author fixes while acting as reviewer.
-2. Test each acceptance criterion and every material factual claim against the evidence ledger.
-3. Look for omissions, contradictions, fabricated support, stale assumptions, unsafe actions, unusable formatting, and failure to verify in the target environment.
-4. Check whether the deliverable advances the actual goal rather than merely matching its requested shape.
-5. Identify what the author and user may not have considered.
-6. Name the single strongest unasked expert question and its consequence.
-7. Report only material findings. Combine duplicates and point to exact locations when possible.
-
-## Decide
-
-- `APPROVE`: no critical or major finding remains. Minor optional improvements may be noted but cannot block approval.
-- `REVISE`: one or more fixable critical or major findings remain. State the smallest required change for each.
-- `BLOCK`: a required decision, authority, source, or safe execution path is absent and the author cannot resolve it within scope.
-
-Confidence is not a substitute for evidence. Do not approve because the prose sounds plausible.
-
-## Output
-
-Return only one JSON object matching this shape:
-
-```json
-{
-  "decision": "APPROVE",
-  "summary": "One-sentence basis for the decision.",
-  "findings": [],
-  "strongest_unasked_question": "The highest-leverage omitted question.",
-  "question_consequence": "What changes if its answer differs.",
-  "confidence": "high"
-}
-```
-
-Each finding must contain `id`, `severity` (`critical`, `major`, or `minor`), `criterion`, `location`, `evidence`, and `required_change`. Use an empty findings array only for approval. Validate a saved decision with:
-
-```text
-python skills/necktie-review/scripts/validate_review.py review.json
-```
-
-Do not include markdown around the JSON, private reasoning, or an edited artifact.

package/skills/necktie-review/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Necktie Review"
-  short_description: "Gate outputs against evidence and criteria"
-  default_prompt: "Use $necktie-review to independently review this deliverable."
-policy:
-  allow_implicit_invocation: false

package/skills/necktie-review/references/reviewer-rubric.md

@@ -1,29 +0,0 @@
-# Necktie reviewer rubric
-
-## Order of review
-
-1. **Authority and safety**: Is the action permitted, reversible where appropriate, and within the agreed scope?
-2. **Goal fit**: Does the artifact support the user's actual outcome and audience?
-3. **Evidence integrity**: Are material claims traceable to eligible, current sources? Are method context and prior outputs kept out of the evidence chain?
-4. **Correctness and completeness**: Are calculations, logic, content, and required sections accurate and sufficient?
-5. **Usability**: Can the intended audience use the result in its target environment?
-6. **Verification**: Were the relevant tests, renders, checks, or inspections performed, and do their results support completion?
-7. **Economy**: Is the solution no larger or more complex than the goal requires?
-
-## Severity
-
-- `critical`: could cause unsafe action, material loss, invalid conclusion, unauthorized change, or failure of the central deliverable.
-- `major`: violates an acceptance criterion, leaves a material unsupported claim, omits a necessary component, or prevents intended use.
-- `minor`: real but non-blocking defect that does not change the decision or intended use.
-
-Do not inflate preferences into findings. A valid finding states the violated criterion, exact location, concrete evidence, and smallest required change.
-
-## Decision examples
-
-- Approve a sound artifact with an optional wording improvement; record it only as a minor finding if useful.
-- Revise when a KPI definition lacks a denominator, a cited claim is unsupported, a requested file does not render, or a required test fails.
-- Block when the user must choose between materially different scopes, required private data is unavailable, or execution needs authority the run does not possess.
-
-## Independence
-
-Review the artifact that exists, not the artifact you imagine the author intended. Do not fix it during the review pass. If revising later, leave reviewer role and return to author role first.

package/skills/necktie-review/scripts/validate_review.py

@@ -1,110 +0,0 @@
-#!/usr/bin/env python3
-"""Validate the JSON decision emitted by the Necktie reviewer skill."""
-
-from __future__ import annotations
-
-import argparse
-import json
-from pathlib import Path
-import sys
-
-
-TOP_LEVEL_KEYS = {
-    "decision",
-    "summary",
-    "findings",
-    "strongest_unasked_question",
-    "question_consequence",
-    "confidence",
-}
-FINDING_KEYS = {"id", "severity", "criterion", "location", "evidence", "required_change"}
-DECISIONS = {"APPROVE", "REVISE", "BLOCK"}
-SEVERITIES = {"critical", "major", "minor"}
-CONFIDENCE = {"high", "medium", "low"}
-
-
-def nonempty_string(value: object) -> bool:
-    return isinstance(value, str) and bool(value.strip())
-
-
-def validate_review(value: object) -> list[str]:
-    errors: list[str] = []
-    if not isinstance(value, dict):
-        return ["review must be a JSON object"]
-
-    missing = sorted(TOP_LEVEL_KEYS - value.keys())
-    extra = sorted(value.keys() - TOP_LEVEL_KEYS)
-    if missing:
-        errors.append(f"missing top-level keys: {', '.join(missing)}")
-    if extra:
-        errors.append(f"unexpected top-level keys: {', '.join(extra)}")
-    if missing:
-        return errors
-
-    decision = value["decision"]
-    if decision not in DECISIONS:
-        errors.append(f"decision must be one of: {', '.join(sorted(DECISIONS))}")
-    for field in ("summary", "strongest_unasked_question", "question_consequence"):
-        if not nonempty_string(value[field]):
-            errors.append(f"{field} must be a non-empty string")
-    if value["confidence"] not in CONFIDENCE:
-        errors.append(f"confidence must be one of: {', '.join(sorted(CONFIDENCE))}")
-
-    findings = value["findings"]
-    if not isinstance(findings, list):
-        errors.append("findings must be an array")
-        return errors
-
-    blocking_findings = 0
-    seen_ids: set[str] = set()
-    for index, finding in enumerate(findings):
-        prefix = f"findings[{index}]"
-        if not isinstance(finding, dict):
-            errors.append(f"{prefix} must be an object")
-            continue
-        missing_finding = sorted(FINDING_KEYS - finding.keys())
-        extra_finding = sorted(finding.keys() - FINDING_KEYS)
-        if missing_finding:
-            errors.append(f"{prefix} missing keys: {', '.join(missing_finding)}")
-        if extra_finding:
-            errors.append(f"{prefix} unexpected keys: {', '.join(extra_finding)}")
-        if missing_finding:
-            continue
-        for field in FINDING_KEYS - {"severity"}:
-            if not nonempty_string(finding[field]):
-                errors.append(f"{prefix}.{field} must be a non-empty string")
-        if finding["severity"] not in SEVERITIES:
-            errors.append(f"{prefix}.severity must be one of: {', '.join(sorted(SEVERITIES))}")
-        elif finding["severity"] in {"critical", "major"}:
-            blocking_findings += 1
-        if finding["id"] in seen_ids:
-            errors.append(f"duplicate finding id: {finding['id']}")
-        seen_ids.add(finding["id"])
-
-    if decision == "APPROVE" and blocking_findings:
-        errors.append("APPROVE cannot contain critical or major findings")
-    if decision in {"REVISE", "BLOCK"} and blocking_findings == 0:
-        errors.append(f"{decision} requires at least one critical or major finding")
-    return errors
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("review", type=Path)
-    args = parser.parse_args(argv)
-    try:
-        value = json.loads(args.review.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        print(f"invalid: {exc}", file=sys.stderr)
-        return 2
-    errors = validate_review(value)
-    if errors:
-        for error in errors:
-            print(f"invalid: {error}", file=sys.stderr)
-        return 1
-    print("valid Necktie review")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())