---
name: sf-repo-orientation
description: Build a sparse SF-native repo orientation map or subsystem map. Use inside automatic workflows when SF needs durable codebase orientation before planning or implementation.
user-invocable: false
model-invocable: true
side-effects: file-writes
permission-profile: normal
triggers:
  - research
  - plan
  - "*"
---

# SF Repo Orientation

Use this skill to generate compact repository documentation for future agents and
humans. The output is an SF-native codebase map, not a Factory upload.

## Output

Default location:

- `.sf/repo-map/` for runtime working context.
- `docs/generated/repo-map/` only when the user wants tracked generated docs.

Prefer `.sf/repo-map/` for autonomous workflow context so tracked docs stay sparse.

## Survey

Use two passes:

1. Structural: README, AGENTS, package manifests, build/test config, docs,
   entrypoints, CI, and top-level directories.
2. Source: routes, commands, providers, services, workflows, tests, generated
   artifacts, and feature flags.

Reconcile source-derived topics with directory enumeration. If a non-trivial
directory is skipped, record the reason in one sentence.

## Pages

Keep the repo map small by default. **This project uses UPPERCASE filenames** to
match the `.sf/` operational file convention (DECISIONS.md, KNOWLEDGE.md, etc.):

- `INDEX.md`: what this repo is, how to run it, where to start.
- `ARCHITECTURE.md`: major subsystems and data/control flow.
- `WORKFLOWS.md`: build, test, release, autonomous/SF flows.
- `SUBSYSTEMS.md`: table of subsystem, path, purpose, owner signal, tests.
- `GLOSSARY.md`: project terms only.

Add subsystem pages only when the table would become unreadable.

## Style

- Optimize for context reload, not publication.
- Use bullets and tables.
- Link to canonical docs instead of copying them.
- Avoid prose history unless it changes how someone should work.
- Mark stale or uncertain facts explicitly.

## Verification

Before finishing:

- Check every referenced path exists or is intentionally historical.
- Run cheap repo discovery commands again if files changed during the scan.
- Leave a short freshness note with date, commit, and commands used.
