Internal Tools

.factory/skills/internal-tools/
├── SKILL.md
├── rbac.md (optional)
├── audit-patterns.md (optional)
└── operations-checklist.md (optional)

---
name: internal-tools
description: Design, implement, or extend internal tools that help employees operate the system safely and efficiently, while respecting access controls and audit requirements. Use when building for internal staff interacting with production-adjacent systems.
---
# Internal Tools

## Purpose

Design, implement, or extend internal tools that help employees operate the system safely and efficiently, while respecting access controls and audit requirements.

## When to use this skill

- The audience is **internal staff** (engineers, SREs, support, operations, finance, etc.).
- The tool interacts with **production-adjacent systems** (feature flags, incidents, customer data, billing, etc.).
- The change is scoped to internal workflows and does not directly alter customer-facing UX.

## Inputs

- **User personas** and teams who will use the tool.
- **Workflows** to support (create/update actions, approvals, review flows).
- **Systems touched**: services, queues, flags, and data stores.
- **Risk classification**: what can go wrong if the tool misbehaves or is misused.

## Out of scope

- Tools that require new identity providers or SSO integrations.
- Changes that bypass existing approval or change-management processes.
- Direct manual-write tooling for core financial or compliance systems without explicit approval.

## Conventions

- Use the **standard stack** for internal tools (framework, component library, backend pattern) already used in the repo.
- Apply **role-based access control** and logging patterns consistently.
- Prefer **read-only views and guarded actions** (confirmation dialogs, requiring justification text, etc.) for high-risk operations.

## Required behavior

1. Implement flows that make the happy path fast while making destructive actions clearly intentional.
2. Ensure all state changes are logged with **who**, **what**, and **when**, and link to existing audit/logging infrastructure.
3. Provide clear feedback on success, errors, and partial failures.
4. Design for operational debugging: include ids, timestamps, and links to related systems.

## Required artifacts

- Frontend and backend changes in the appropriate internal-tools modules.
- **Automated tests** for critical operations (at least unit tests; integration tests where harnesses exist).
- Baseline **operational runbook entry** or link explaining how to use the tool and what to do when it fails, if required by your team.

## Implementation checklist

1. Clarify workflow boundaries and risk level with stakeholders.
2. Identify existing components, endpoints, and patterns to reuse.
3. Implement the UI, backend handlers, and data access using established abstractions.
4. Add safeguards: confirmations, rate limiting, or approvals depending on risk.
5. Wire up logging and metrics so usage and failures are visible.
6. Add or update tests and any required runbook entries.

## Verification

Run the standard validation commands for the relevant apps/services (tests, lint, type checks). In addition:

- Exercise both **happy paths and failure modes** in a safe environment.
- Confirm that audit logs and metrics reflect actions accurately.

The skill is complete when:

- Validation commands pass.
- Flows behave correctly in staging or an equivalent environment.
- Stakeholders can perform their target workflows without manual DB access or unsafe workarounds.

## Safety and escalation

- If an operation could cause **irreversible data loss or external customer impact**, require higher-level approvals and consider additional controls (dual control, time-boxed access, or break-glass procedures).
- If you discover that existing internal tools bypass critical controls, document this clearly and escalate through the appropriate risk or security channel.