feat(skills): the human-surface reference — decisions via `AskUserQuestion`, waiting per mode, completion with a link; skills call `sequant comment render` and `sequant mutation …` instead of hand-rendering

Aperta
  • Qualcosa non va?
#1,606 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
github, typescript
Ambito
developer-experience, tooling

Direzione di ricerca

Start with the referenced skill files under .claude/skills/ and their mirrors in templates/skills/ and plugin/skills/; inspect scripts/lint-skill-gates.ts and its test for the human-surface checks. The work is blocked by issues #1603–#1605 and the plugin freeze lift. Done means all seven acceptance criteria pass, including synchronized skill mirrors and the documented mutation check.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

graph-2026-10-ergonomics

Epic: graph-2026-10-ergonomics Tier: judgment Execution: split Blocked by: #1603, #1604, #1605 (the plugin freeze lifted 2026-11-06)

  • Blocked by: #1603
  • Blocked by: #1604
  • Blocked by: #1605

Problem

Of 125 human turns in 12 audited sessions, ~30 were approvals, and ~18 of the enumerated items already carried "I recommend yes". The owner asked twice for an interactive prompt instead of a prose list. Only 3 of 20 skills allow AskUserQuestion. Interactive sessions blocked 48.7 minutes in foreground sleeps while exec §3 (correctly, #1032) forbids background waits under the orchestrator and no skill states the interactive rule. 6 of 17 corrections were "Merged?" / "where is it". §5 D-3.2..D-3.5 and §4 D-2.4.

Decisions

ID Decision Rejected alternative
S-1 .claude/skills/_shared/references/human-surface.md holds: decisions (one AskUserQuestion, recommended first, act on what you already recommend; merge consent, live writes and open calls stay questions), waiting per mode (orchestrator: foreground, bounded, once; interactive: background + notification or sequant merge --watch, never a foreground sleep over 60 s), completion (final message names the PR/issue/run URL) one rule written into each skill (drift)
S-2 spec, qa, exec, merger, release, fullsolve, assess, verify cite it in one line; lint:skill-gates carries one exact phrase per rule trusting the citation to stay
S-3 spec and interactive qa pipe their comment through sequant comment render; exec and qa replace the hand-typed marker steps with sequant mutation begin/check/render keeping the old text as fallback
S-4 AskUserQuestion added to allowed-tools of every skill that presents decisions leaving prose lists

Acceptance Criteria

  • AC-1: The reference exists with the three rule sections. Evidence: grep -cE '^## (Decisions|Waiting|Completion)' .claude/skills/_shared/references/human-surface.md → 3
  • AC-2: The eight skills cite it. Evidence: for s in spec qa exec merger release fullsolve assess verify; do grep -l 'references/human-surface.md' .claude/skills/$s/SKILL.md; done | wc -l | tr -d ' ' → 8
  • AC-3: lint:skill-gates fails when a citing skill drops the waiting phrase. Evidence: npx vitest run scripts/lint-skill-gates.test.ts -t "human-surface" → ≥ 1 passed, 0 failed (mutation: delete the phrase from one skill → that test fails; restore; record in the PR body)
  • AC-4: /qa §6i and /exec no longer instruct the agent to write a SEQUANT_MUTATION line; they call the CLI. Evidence: grep -c 'sequant mutation' .claude/skills/qa/SKILL.md .claude/skills/exec/SKILL.md | awk -F: '{s+=$2} END{print s}' → ≥ 2 and grep -c '<!-- SEQUANT_MUTATION' .claude/skills/exec/SKILL.md → 0
  • AC-5: /spec posts through sequant comment render. Evidence: grep -c 'sequant comment render --kind spec' .claude/skills/spec/SKILL.md → ≥ 1
  • AC-6: Skills that present decisions list AskUserQuestion in allowed-tools. Evidence: for s in spec qa merger release fullsolve assess verify; do grep -l 'AskUserQuestion' .claude/skills/$s/SKILL.md; done | wc -l | tr -d ' ' → 7
  • AC-7: Mirrors are in sync. Evidence: npm run lint:skill-sync → exit 0

May touch

.claude/skills/**, templates/skills/**, plugin/skills/** (through sync:skills), scripts/lint-skill-gates.ts and test, CHANGELOG.

Non-Goals

  • Changing orchestrator waiting (#1032 stands).
  • Any TS change beyond the lint.

Done when

An interactive session driven through sequant skills asks its open questions in one prompt, waits in the background, posts a comment whose visible part is the verdict and AC table, and ends with a link.

Lingua principale
TypeScript
Stelle
1
Fork
1
Merge medio
11h 3m
PR unite (30g)
84

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di sequant-io/sequant

Tutte le issue di sequant-io/sequant

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.