# Pathrule Pattern: Developer Onboarding (1.0.0) # ::pathrule:package:developer-onboarding ### [RULE] One unattended setup command proves the canonical environment (path: /scripts/setup) A checklist of manual fixes is not a reproducible environment. Provide one canonical setup entry point that checks supported operating systems and architecture, installs or verifies pinned tool versions, restores dependencies, creates local configuration from safe templates, prepares services and sample data, and runs a bounded health check. Re-running it must be safe. - Fail with the missing prerequisite, observed value, expected value, and exact recovery action. - Never download or print production secrets, personal credentials, or unreviewed remote scripts. - Keep optional heavy components behind named profiles while the default supports the first contribution. - Execute the same path on a clean runner or disposable development container on a schedule. Verification: Start from a clean supported image, run setup twice, remove each prerequisite, and interrupt midway; confirm recovery is deterministic and the health check proves readiness. --- ### [RULE] The first change crosses the real contribution path (path: /docs/onboarding) An onboarding task that edits a typo proves almost nothing about the engineering system, while a production-critical feature is too risky and ambiguous. Maintain a small representative change with a clear expected outcome, owned test fixture, visible design boundary, review instructions, and rollback path. Rotate it when the product or architecture changes. - Include discovery of the relevant owner, local reproduction, implementation, focused tests, full required checks, and pull-request context. - State which generated files, migrations, flags, documentation, and screenshots apply to the change. - Avoid novelty work whose correct result has never been implemented or reviewed before. - Capture every undocumented dependency or permission discovered during completion as onboarding-system work. Verification: Have a maintainer complete the path from a clean environment using only public onboarding material; confirm no private message or remembered workaround is required. --- ### [MEMORY] The development container is a supported environment contract (path: /.devcontainer) A development container can make toolchains reproducible, but only if it is maintained as a supported product rather than a stale sample. Keep its base image, features, extensions, forwarded ports, service dependencies, user permissions, caches, and post-create command versioned and reviewable. Do not embed credentials or assume host-only state. Run the same repository checks inside the container and document which workflows still require host capabilities. Update local and container setup together when a tool version or service changes. Test rebuild from no cache as well as ordinary reopen. See /scripts/setup for the canonical idempotent preparation and /docs/onboarding for the newcomer journey it must support. --- ### [MEMORY] Prerequisites and access requests have named owners (path: /docs/onboarding) New contributors should not discover permissions one failing command at a time. Inventory required and optional tools, identity groups, repositories, package registries, cloud environments, databases, feature systems, communication channels, and paid licenses. For each, state purpose, request path, approver or owner, expected lead time, least-privilege role, and a safe verification step. Separate pre-start requests from access that should be granted only after training or task assignment. Never ask a newcomer to share a token in chat or copy another person's credentials. Keep alternatives for external contributors explicit. Track recurring delay by owner and system so onboarding friction leads to a service-level fix rather than more prose. --- ### [MEMORY] Sample data is safe, deterministic, and representative (path: /examples) A blank database hides important behavior, while a production snapshot creates privacy, security, and drift risk. Build versioned synthetic fixtures that represent primary roles, tenant boundaries, common lifecycle states, permissions, billing states, time zones, and a small set of deliberate edge cases. Give fixtures stable identifiers and a fast reset path. Mock or sandbox external integrations with clearly visible behavior and no production credentials. Keep fixture generation deterministic enough for tests while avoiding magic values known only to maintainers. Document login or identity flows without committing passwords that could work elsewhere. See /scripts/setup for seeding and /docs/onboarding for the scenarios a newcomer should exercise. --- ### [MEMORY] Onboarding friction is product telemetry (path: /docs/onboarding) Measure onboarding to improve the system, not rank newcomers. Capture milestone times and blocker categories with consent and minimal personal detail: access delay, machine or network issue, tool mismatch, setup failure, missing fixture, unclear architecture, test instability, review delay, and ownership ambiguity. Pair metrics with short qualitative feedback after the experience. Segment by supported environment and contributor type so averages do not hide structural gaps. Review repeated workarounds and private-message dependencies as defects with owners and deadlines. Publish improvements and close the loop with recent contributors. Do not use speed alone as a performance signal because prior context and task complexity vary substantially. --- ### [SKILL] verify-onboarding-path (path: /docs/onboarding) --- name: verify-onboarding-path description: Verify the complete developer onboarding journey from clean machine to reviewed first change. --- # Verify Onboarding Path 1. Choose a supported contributor profile and start from a clean machine or container with no repository cache, credentials, or remembered project state. 2. Follow only the published prerequisite, access, setup, sample-data, run, debug, test, and contribution instructions; timestamp each checkpoint. 3. Complete the maintained first-change exercise through local checks, pull-request context, CI, review feedback, and the documented delivery or cleanup step. 4. Record every manual workaround, private question, stale command, ambiguous owner, missing permission, unsafe secret path, flaky check, and environment-specific assumption. 5. File scoped fixes with owners, update the journey, and rerun from clean state until the evidence is reproducible. Do not coach the test participant around a defect without recording the defect first. --- ### [SKILL] maintain-onboarding-system (path: /scripts/setup) --- name: maintain-onboarding-system description: Keep onboarding assets synchronized with changes to tools, architecture, access, data, and contribution workflow. --- # Maintain Onboarding System 1. Identify whether the change affects prerequisites, tool versions, container image, access, secrets, services, seed data, ports, commands, generated files, tests, CI, review, or delivery. 2. Update the canonical setup and machine-readable configuration first, then revise the journey and first-change exercise to match the executable behavior. 3. Remove superseded instructions and workarounds instead of layering another exception on top. 4. Rebuild from a clean environment, run setup twice, restore sample data, complete the affected checkpoint, and record timing and output evidence. 5. Notify the onboarding owner of new lead-time or permission dependencies and schedule a full journey verification when risk crosses several boundaries. A change is not complete while the supported newcomer path still describes the old system.