# Professional Development Workflow

## Purpose

Use this workspace to practice professional software development habits while building useful systems.

The goal is not ceremony for its own sake. The goal is to make work clear, safe, reviewable, and resumable — the same skills expected in software/devops roles.

## Core Loop

For non-trivial work, use this loop:

1. **Ticket** — define the work item.
2. **Spec** — design the approach when the work is complex, security-sensitive, infrastructure-related, or data-affecting.
3. **Branch / small change set** — keep changes reviewable.
4. **Implementation** — build the smallest useful increment.
5. **Tests / verification** — prove what changed works.
6. **Diff review** — inspect what changed before committing.
7. **Commit** — save a coherent checkpoint with a meaningful message.
8. **Deploy / operate** — if server changes are made, log them.
9. **Retrospective notes** — capture lessons or follow-up tickets.

## Tickets

A good ticket answers:

- What outcome do we want?
- Why does it matter?
- What is in scope / out of scope?
- What does done mean?
- What questions remain?

Tickets in this repo live under:

```text
tickets/active/
tickets/done/
tickets/archive/
```

## Specs

Use specs before:

- infrastructure changes
- security-sensitive work
- data-affecting work
- multi-step software builds
- anything where rollback matters

A spec should capture:

- objective
- requirements
- design
- dependencies
- security/safety concerns
- backup/rollback plan
- acceptance criteria
- decisions

## Git Workflow

Preferred local workflow:

```sh
git status
git diff
# make focused changes
# run tests/checks
git diff
git add <files>
git commit -m "Short imperative summary"
```

Commit guidelines:

- Commit logical units of work.
- Keep generated files, secrets, and local caches out of git.
- Write messages as if completing the phrase: "This commit will ..."
  - Good: `Add Talk assistant voice transcription`
  - Weak: `stuff` / `updates`

## Testing / Verification

Every change should have some verification, even if simple:

- unit test
- script self-test
- syntax check
- service status check
- manual test steps
- log inspection

Record important verification in tickets, runbooks, or change logs.

## Server Change Logging

When changing servers, update:

```text
docs/server-change-log.md
```

Include:

- host
- reason
- actions taken
- files/services changed
- verification
- rollback notes

## How the Assistant Should Teach

The assistant should teach professional workflow incrementally:

- explain what step we are doing and why
- avoid long lectures unless asked
- call out tradeoffs and risks
- show useful commands
- invite the user to review diffs or approve risky changes
- relate homelab practices to workplace practices

## Current Emphasis

For the current Nextcloud/Talk assistant work, emphasize:

- ticket/spec discipline
- safe deployment
- server change logs
- small commits
- service verification
- rollback thinking