he-spec Entry

Use when the user needs a Harness Engineering specification artifact before planning or implementation.

Context disposition: Apply the context-disposition policy: move important still-valid context to references and index it when meaningful; intentionally discard stale, duplicated, unsafe, superseded, or low-signal text.

Philosophy

• Clarify the behavior contract before planning or coding.
• Keep acceptance criteria concrete enough for downstream verification.

When to use

Use he-spec when the user needs the WHAT-before-HOW contract for a feature, UI behavior, bug, QA report, or ambiguous implementation request.

Required inputs

• A brainstorm, Linear issue, existing spec, QA report, UI source, feature description, or behavior gap.
• Known caller-facing interfaces, domain terms, source acceptance IDs, and relevant repo paths.
• Parent/child issue context and branch/PR metadata when the work is already tracked.

Deliverables

• A spec-mode decision and implementation-grade behavior contract.
• Stable SA or VAC acceptance IDs, explicit non-goals, risks, observability notes, and planning-ready first slice.
• For tracked work, Linear issue frontmatter plus a Linear Acceptance Traceability table.

Core Contract

• Specify the WHAT before he-plan; do not implement code here.
• Resolve the active Linear issue for non-trivial tracked work; stop and request or create one if it is missing.
• Ground the spec in the source artifact, QA report, Linear issue, UI source, feature description, and any CONTEXT.md terms that shape behavior.
• Detect caller-facing interfaces early: module, API, CLI, plugin, tool, service, data-access, or shared-helper boundaries.
• Name the selected contract, acceptance criteria, failure/recovery behavior, observability expectations, and planning-ready first slice.
• Route unresolved contract gaps to he-deepen-spec; route complete specs to he-plan.

Procedure

1. Resolve source artifact, Linear issue, and domain terms.
2. Define expected behavior, non-goals, interface shape, and acceptance IDs.
3. Add Linear acceptance traceability and the first planning slice.

Traceability

Tracked specs need Linear Work Item Contract frontmatter and a Linear Acceptance Traceability table mapping the issue to SA or VAC acceptance IDs, parent/child context when relevant, and the planning handoff.

Validation

• Confirm required frontmatter and mode-specific sections exist.
• Confirm SA or VAC IDs are concrete enough for planning.
• Confirm tracked specs include Linear issue frontmatter and acceptance traceability.
• For written tracked specs, run python3 Infrastructure/scripts/validation-and-linting/he_linear_traceability_lint.py <spec-path> as a required gate.
• Stop at the first failed gate.

Constraints

• Redact secrets, credentials, tokens, and sensitive data by default.
• Do not plan sequencing or implement code from this skill.
• Use Linear issues or comments for durable decisions.

Anti-patterns

• Inventing undocumented behavior.
• Sending an unspecified interface to planning.
• Sending tracked work onward without Linear acceptance traceability.

Examples

• "Turn this Linear issue into a spec before planning."
• "Specify this QA behavior gap with acceptance criteria."

Failure mode

If required behavior, interface boundaries, or tracker context cannot be resolved, stop and ask for the missing source instead of inventing acceptance criteria.

Gotchas

• Do not plan sequencing or implement code from this skill.
• Do not treat GitHub PRs as the tracker of record; use them as delivery evidence linked back to Linear.
• Route incomplete caller-facing contracts to he-deepen-spec before he-plan.

References

• Full guide: Plugins/harness-engineering/fixtures/preserved-context/skills/he-spec/SKILL.full.md
• Spec artifact contract: Plugins/harness-engineering/fixtures/preserved-context/skills/he-spec/references/spec-artifacts.md
• Spec mode rules: Plugins/harness-engineering/fixtures/preserved-context/skills/he-spec/references/spec-modes.md
• Subagent routing: Plugins/harness-engineering/references/subagent-routing.md
• Domain and QA routing: Plugins/harness-engineering/references/domain-model-routing.md, Plugins/harness-engineering/references/qa-intake-routing.md