Imported from DanielMulec/mindpingsskill (AGENTS.md). Install upstream with npx skills add DanielMulec/mindpingsskill. Copyright stays with the author.

MindPings Skillification - Terminology Bible

This glossary is the canonical terminology for the project of turning MindPings into an OpenClaw skill.

Pragmatic Mode (mandatory behavior for GPT-5.2 / Codex)

• Trigger: If the user says they are frustrated, blocked, or repeated fixes keep failing/timeing out, switch to Pragmatic Mode immediately.
• Priority: Optimize for reliable user outcome now, not architectural purity.
• Default strategy in Pragmatic Mode:
  • Prefer smallest reliable fix first.
  • Avoid large refactors unless explicitly requested.
  • Propose at least one alternative approach (including a simpler/non-deterministic fallback) with trade-offs.
• Pivot rule: If current approach fails repeatedly, do not keep grinding on it; propose a different path and ask for a quick yes/no choice.
• Drop-old-way rule: If the user prefers a new approach, replace the old one without hesitation and document the change.
• Communication: Keep updates concrete and short ("what failed -> what we change -> why this is safer/faster").

Single Source of Truth (mandatory)

• Canonical code source is always: /home/dmulecKDE/projekte/mindpingsskill.
• Codex must edit code only in the canonical project repo.
• Codex must never treat /home/dmulecKDE/.openclaw/workspace/skills/mindpings as an editable source repo.
• The OpenClaw skill copy is a deployed mirror only and must be synced from GitHub main.
• Required workflow after code/documentation changes:
  1. Commit + push from canonical project repo.
  2. Sync OpenClaw copy from GitHub main.
  3. Verify both copies are clean and on the same commit hash.
• Enable versioned git hooks in the canonical repo:
  • Run scripts/install_git_hooks.sh once.
  • Pre-push hook must run source-of-truth checks before allowing push.
• Use scripts/source_of_truth_guard.sh for sync/verification enforcement.

Documentation requirement (mandatory)

• Always consult the OpenClaw and ClawHub documentation for any packaging, cron, skill format, or installation guidance.
• When answering questions or planning changes that touch OpenClaw/ClawHub behavior, use the official docs as the primary source of truth.

Collaboration stance (mandatory)

• Codex and user are equals; communicate accordingly.
• If the user proposes a risky or suboptimal technical idea, call it out clearly and explain the reasoning.

Quality priority (mandatory)

• Quality is the highest priority in all aspects of our work.

File size constraint (mandatory)

• Maximum 400 lines of code per file. If a file would exceed this, split it.

Inline comments (mandatory)

• Inline comments must explain both how the code works and why the approach was chosen.

Core nouns

• Reminder (aka "Ping Template")

  • The user-authored text/content that will be sent later.
  • In RandomReminderApp9, this is stored as Reminders.reminderName.

• Ping (aka "Delivery")

  • One actual message sent to the user at a specific time.
  • A Ping is an instance of a Reminder.

• Active Hours (aka "Wake Window")

  • The allowed time range in which pings may be scheduled.
  • Stored as wakeUpTime + sleepTime in the Android app.

Planning + scheduling

• Plan

  • The set of Pings scheduled for a specific day (or for the remaining part of today after a change).

• Planning Run

  • The act of generating a Plan.
  • In the skill, this will run daily around 00:00 and may also run as a catch-up if the agent was offline.

• Replan

  • Cancel remaining scheduled Pings for today and regenerate a new Plan for the rest of today.
  • Triggered by user actions like add/delete/modify reminders or changing Active Hours.

• Event

  • One scheduled Ping inside a Plan: { eventId, reminderId, plannedAt, text }.

• Event ID

  • Stable identifier for an Event (usually a hash of {date, reminderId, plannedAt}).
  • Used for idempotency (avoid double-sends on retries).

Cron / execution (OpenClaw)

• Cron Job

  • A scheduled job stored by OpenClaw's Gateway scheduler.

• One-shot Job

  • A cron job scheduled to run once at an exact timestamp.
  • In the skill, each planned Ping becomes a one-shot job.
  • It must not keep firing after the first send (prefer deleteAfterRun: true or self-delete).

• Daily Planner Job

  • The cron job that runs once per day to generate today's Plan.

• Guard Job (aka "Catch-up Job")

  • A cron job that ensures "today is planned" even if the daily job was missed (e.g. Gateway was offline).

OpenClaw execution semantics

• systemEvent (cron payload kind)

  • A cron job mode that enqueues a system event into the main session and is processed by the heartbeat runner.
  • Good when you explicitly want main-session context and "normal heartbeat behavior".

• agentTurn (cron payload kind)

  • A cron job mode that runs a dedicated agent turn in an isolated cron:<jobId> session.
  • Good for background work and for time-accurate delivery (pings), because it can deliver output directly to the user.

Operational caveats (Kimi K2.5 + OpenClaw cron)

• Do not rely on --timeout behavior inside isolated Kimi K2.5 cron runs as a correctness signal.
  • Treat timeout failures as "unknown outcome" and verify side effects before retrying.
• openclaw cron add can time out but still create the job in gateway.
  • Blind retries can duplicate one-shot ping jobs.
• Do not add --timeout to openclaw message send in cron ping delivery paths.
  • Historical production failures showed unknown option '--timeout' for that subcommand.
• OpenClaw cron agentTurn payloads execute as model instructions in isolated sessions.
  • Keep payloads explicit ("run this exact command"), deterministic, and with absolute paths.
• Keep cron payloads explicit and operational (exact command execution), with minimal nested OpenClaw calls per run.

Correctness + reliability

• Stale Plan

  • A plan is considered stale if:
    • lastPlanDate != today, or
    • now - lastPlannedAt > 24h.

• Requested vs Scheduled

  • When users set max/day, the planner may schedule fewer pings if constraints make it impossible.
  • UX should always show "requested N, scheduled M" for clarity.

• Missed Ping

  • A ping whose planned time has passed while OpenClaw (or the channel delivery) was unavailable.

• Missed policy

  • The rules for what to do with missed pings (e.g. "expire missed pings for today; keep future plans").

UX / user-facing flows

• Onboarding

  • The first-run setup flow: welcome, active hours, first reminder, max/day, demo ping, enable automation.

• Demo ping

  • A single immediate ping sent during onboarding to show the user how pings look.
  • Not part of the daily plan.

• Pause / Resume

  • Pause disables sending (and/or scheduling) without deleting reminders.
  • Resume reenables daily planning and delivery.

Randomization

• Deterministic randomization

  • Random-looking scheduling generated via a deterministic PRNG with a seed.
  • Same inputs -> same plan (useful for debugging, reproducibility, token efficiency).

• Seed salt

  • User-specific secret/random value included in the seed so different users don't share identical schedules.