ks-help

Preamble: see templates/preamble.md

Help

Keystone's entry point. One job: give the user one copy-ready next sentence.

Responsible for: recommending one skill, giving a copy-ready prompt. Not responsible for: deciding entry_mode, mutating workflow state, replacing orchestrate.

---

Procedure

Step 1: Run first-run intro if needed

Check if this is the user's first time. state init already created flag files and set defaults. This step only prints the intro message once.

_KS_CLI="${KEYSTONE_CLI:-./keystone}"
_FIRST_RUN=$($_KS_CLI state get first_run_complete 2>/dev/null | tr -d '"')

if [ "$_FIRST_RUN" != "true" ]; then
  $_KS_CLI state set first_run_complete true >/dev/null 2>&1 || true
  echo "=== First Run ==="
  echo "Keystone: flexible entry, honest exit."
  echo "You can finish your first real task in about 5 minutes."
  echo "Quickstart: docs/quickstart.md"
  echo ""
  echo "Telemetry is off by default. Change with:"
  echo "  ./keystone state set telemetry_consent community"
  echo "  ./keystone state set telemetry_consent anonymous"
  echo "  ./keystone state set telemetry_consent off"
  echo ""
fi

• expected: first_run_complete set to true in state on first run only
• subsequent runs: first_run_complete is already true, intro skipped silently
• non-interactive: defaults are telemetry=off, proactive=false (set by state init)

Step 2: Determine the current situation

Read the user's input and classify:

Decision rule: recommend exactly one primary entry. A list of three "maybe" options is not a recommendation.

Step 3: Look up the recommendation

Step 4: Output the recommendation

## Help Recommendation

**Current read**: [one sentence]
**Recommended entry**: `skill-name`
**Why**: [one sentence]

---
**Copy this and send it next:**

> [full copy-ready prompt from the table above]

---

The copy-ready prompt must appear inside a > quote block so the user can spot it immediately.

Step 5: Hand off

Once the recommendation is output, stop. Let the downstream skill do the work. Help does not keep routing ownership.

---

Exception: User names a skill directly

If the user says /ks-review or "I need a review", route directly to that skill. Do not force them back through the recommendation table.

Exception: First-time user with no state

If no .keystone/state.json exists and the user has not described a task, append:

---
**New here?** You can finish a real task in about 5 minutes. Read `docs/quickstart.md` or run:
> /ks-orchestrate Route this task from the correct entry mode and push it to the smallest safe next step.
---

Exception: User asks "what skills exist?"

Show the full scenario table from Step 3. This is the only case where help shows more than one recommendation.

---

Decision Contract

decision: help-guided confidence: 0.9 rationale: One executable entry recommended based on the user's current situation. Help only handles onboarding and scenario triage; it does not replace formal routing. fallback: If help cannot reliably determine the stage, default to orchestrate. escalate: false next_skill: orchestrate next_action: Enter the recommended skill using the copy-ready prompt.

State Update

_KS_CLI="${KEYSTONE_CLI:-./keystone}"
$_KS_CLI state set last_decision "help-guided" >/dev/null 2>&1 || true
$_KS_CLI state set artifacts.last_help_recommendation "${SUGGESTED_SKILL:-orchestrate}" >/dev/null 2>&1 || true

Telemetry

mkdir -p .keystone/telemetry/events
echo "{\"skill\":\"help\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"decision\":\"help-guided\",\"next_skill\":\"${SUGGESTED_SKILL:-orchestrate}\",\"first_run\":$([ -f .keystone/.first-run ] && [ "$(find .keystone/.first-run -mmin +0 2>/dev/null)" != "" ] && echo false || echo true)}" >> .keystone/telemetry/events/$(date +%Y-%m).jsonl

Quality Checklist

• first-run ritual ran if needed, did not repeat
• one primary recommendation was given (not a list)
• the copy-ready prompt is present in a quote block
• the recommendation matches the user's current stage
• help was not turned into a second orchestrate