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

Abierto
  • ¿Algo no está bien?
#1,606 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
github, typescript
Área
developer-experience, tooling

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
1
Forks
1
Merge medio
11 h 3 min
PR fusionados (30 d)
84

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de sequant-io/sequant

Todos los issues de sequant-io/sequant

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.