# Spec Sheet — Log Start

**What you are building:** A slash-command skill that creates one timestamped Markdown entry to mark the start of a work session, leaving the end time blank for a companion "log end" skill to fill.

> Bracketed [PLACEHOLDERS] are yours to fill in for your own project. The original skill contains no credentials; if your variant ever needs one (e.g. to push the log somewhere), supply it from your own secret store and never write it inline in the skill file.

## 1. Purpose
Stamp the moment a work session begins with near-zero friction, so the start time is captured at the true start rather than reconstructed later. Each session becomes one small, version-controllable file. The session description is intentionally NOT collected here — a paired "log end" skill closes the entry and records what was done.

## 2. Activation
- **name:** `log-start`
- **description:** Write it so the model auto-triggers on the natural phrasings. Include the explicit command form and the intent form, and state that it takes no argument. Example: "Record the start of a [PROJECT] work session. Creates a new time-log entry file in [LOG_DIR]/ with the current timestamp. Use when the user runs /log-start or asks to log the start of a work session." Trigger phrases to cover: `/log-start`, "log the start", "start a work session", "begin logging".

## 3. Inputs and preconditions
- **Input:** none from the user. The only data source is the system clock.
- **Optional signal:** if the invocation mentions an alternate environment (e.g. a different runtime/surface), capture that string for the `Environment:` field; otherwise use the default.
- **Precondition:** a writable working tree at [REPO_ROOT]. The skill creates [LOG_DIR]/ if absent, so it need not pre-exist.

## 4. Outputs and side effects
- One new file: `[LOG_DIR]/YYYY-MM-DD-HHMM.md` (time with no colon).
- File contents: a title line, a metadata block (`Start`, `End`, `Environment`), and trailing blank lines reserved for the end-skill's description.
- `End:` is written empty — this is what marks the entry "open".
- A single confirmation line back to the user. No other output, no questions.
- If [LOG_DIR]/ is committed to version control, the entry becomes an externally-dated record on the next commit (commit is out of scope for this skill).

## 5. Environment and dependencies
- A shell with a `date` command (or equivalent) to read the current timestamp.
- A repo or directory at [REPO_ROOT] where [LOG_DIR]/ lives.
- A companion **log-end** skill that reads the same file format to close entries. This skill is half of a pair; define the file format once and have both skills honor it.
- No MCP tools, no network, no external state file. Pure instruction skill — one SKILL.md, no scripts or assets required.

## 6. Procedure
1. Read the current date and time, e.g. `date '+%Y-%m-%d %H:%M'` → `2026-05-06 17:15`.
2. Construct the filename `[LOG_DIR]/YYYY-MM-DD-HHMM.md` by stripping the colon from the time → `[LOG_DIR]/2026-05-06-1715.md`.
3. If `[LOG_DIR]/` does not exist at [REPO_ROOT], create it.
4. Write the entry, substituting the real date and start time:

   ```
   # 2026-05-06 — [PROJECT] work session

   - Start: 17:15
   - End:
   - Environment: [DEFAULT_ENVIRONMENT]

   ```

   Rules: the title's date matches the start date; `End:` is left blank for the end-skill; `Environment:` defaults to [DEFAULT_ENVIRONMENT] but is overridden if the invocation names another; leave two blank lines at the bottom for the description paragraph the end-skill will add.
5. Reply with one line, e.g. `Logged session start: [LOG_DIR]/2026-05-06-1715.md`. Do not elaborate.

## 7. Edge cases and failure handling
- **Filename collision** (two sessions in the same minute): append a disambiguating suffix (e.g. `-b`) rather than overwriting the existing file.
- **Missing log directory:** create it; do not error.
- **No environment mentioned:** use the default; do not ask.
- The skill never blocks on the user — it runs to completion silently.

## 8. Guardrails / hard rules
- Ask the user nothing. Run to completion.
- Do NOT collect or write a session description here — that belongs to the end-skill.
- Leave `End:` empty; the metadata block layout is the contract the end-skill parses, so do not reorder or rename its lines.
- Avoid embedding command substitution like `$(date …)` in a command the skill runs later, if your harness prompts for approval on it; instead read the timestamp first and substitute the literal value. (In Claude Code, `$()` triggers an approval prompt even under a matching allow-rule.)
- Keep the reply to a single line.

## 9. Acceptance criteria
- Running the skill creates exactly one file named `[LOG_DIR]/YYYY-MM-DD-HHMM.md` matching the current time, colon stripped.
- The file's title date equals the start date; `Start:` shows HH:MM; `End:` is blank; `Environment:` is the default (or the override when supplied).
- There are two blank lines after the metadata block.
- A second invocation within the same minute does not overwrite the first; it writes a suffixed file.
- The companion end-skill, run afterward, correctly identifies this file as the open entry purely from `End:` being empty.
- The only chat output is one confirmation line.

## 10. Adapt to your setup
- Replace [PROJECT] (title label), [LOG_DIR] (e.g. `time-log`), [REPO_ROOT], and [DEFAULT_ENVIRONMENT] (e.g. `claude code`).
- Decide your override environments (e.g. other surfaces/runtimes you work from) or drop the `Environment:` field entirely if irrelevant.
- If you want the timestamp committed automatically, add a commit step to the end-skill (keep this skill write-only) or commit [LOG_DIR]/ on your normal cadence.
- Keep the file format identical between this skill and your log-end skill — it is their only interface.

```markdown
---
name: log-start
description: Record the start of a [PROJECT] work session. Creates a new time-log entry file in [LOG_DIR]/ with the current timestamp. Use when the user runs /log-start or asks to log the start of a work session.
---

# Log session start

Creates a new entry in `[LOG_DIR]/` at the repo root to mark the start of a [PROJECT] work session. One file per session.

## What to do
1. Read the clock: `date '+%Y-%m-%d %H:%M'`.
2. Build the filename `[LOG_DIR]/YYYY-MM-DD-HHMM.md` (no colon in the time).
3. Create `[LOG_DIR]/` if it does not exist.
4. Write the fixed entry body: title with the start date, `Start:` filled, `End:` blank, `Environment:` defaulted (override if the invocation names one), two trailing blank lines.
5. Reply with one confirmation line; do not elaborate.

## Important
- Ask nothing; run silently to completion.
- The description is captured by the log-end skill, not here.
- On a same-minute filename collision, append a suffix like `-b`.
```