---
name: housekeeping
description: Run after completing any change to a microservice to bring its generated files, documentation, version, and topology diagram up to date. Skip if the skill you just followed already ran housekeeping as its final step.
---

**CRITICAL**: Read and analyze this microservice before starting. Do NOT explore or analyze other microservices - the instructions in this skill are self-contained to this microservice. NATS ACLs are derived from source at deploy time by `cmd/gencreds` (not at housekeeping time), so a code change here doesn't require regenerating anything in other services.

## Workflow

Copy this checklist and track your progress:

```
Post-change housekeeping:
- [ ] Step 1: Bump the version
- [ ] Step 2: Regenerate the boilerplate
- [ ] Step 3: Vet compilation
- [ ] Step 4: Document the microservice
- [ ] Step 5: Log the prompts
- [ ] Step 6: Visualize workflows
- [ ] Step 7: Chart the topology
```

#### Step 1: Bump the Version

Increment the `Version` const in `myserviceapi/definition.go`. The generated `intermediate.go` references it, so the bump takes effect when the boilerplate is regenerated in the next step.

#### Step 2: Regenerate the Boilerplate

Run `go run github.com/microbus-io/fabric/cmd/genservice .` from the microservice's directory. From `myserviceapi/definition.go` it regenerates all five derived artifacts: `myserviceapi/client.go`, `intermediate.go`, `mock.go`, `mock_test.go`, and `manifest.yaml`.

The `manifest.yaml` `general` block (`name`, `hostname`, `description`, `package`) is derived from the `definition.go` consts and the module path; `modifiedAt` is bumped to the current UTC time only when other content actually changed. Review the diff.

NATS ACL files are NOT generated at housekeeping time - they're derived from source by `cmd/gencreds` at deploy. Do not invoke `cmd/gencreds` from this skill; it consumes operator-sensitive material (the account NKey) and runs in the CD pipeline.

#### Step 3: Vet Compilation

Run `go vet ./...` from the project root and fix any compilation errors before proceeding.

#### Step 4: Document the Microservice

Skip this step if instructed to be "quick" or to skip documentation, or if the change introduces no new design rationale or tradeoffs worth capturing.

Update the microservice's local `CLAUDE.md` file to reflect the changes. If the file does not exist, create it with the hostname as an H1 heading (from `manifest.yaml`). Capture purpose, design rationale, tradeoffs, and the context needed for someone to safely evolve this microservice in the future. Focus on the reasons behind decisions rather than describing what the code does.

#### Step 5: Log the Prompts

Skip this step if the change is too minor to affect how you'd describe the microservice to a new agent.

Update `PROMPTS.md` to reflect the current capabilities of the microservice - what you would need to prompt to reproduce it from scratch today. Rewrite or extend the existing content as needed. The goal is a concise, up-to-date description a future agent could use to recreate the microservice, not a history of every change.

#### Step 6: Visualize Workflows

Run `go run github.com/microbus-io/fabric/cmd/genworkflowmmd --path .` from the microservice's directory to generate a Mermaid flowchart for each workflow endpoint.

#### Step 7: Chart the Topology

Run `go run github.com/microbus-io/fabric/cmd/gentopology --bundle main/main.go` from the project root to regenerate `main/topology.mmd`.