project-development-mindset

What this skill does

# Project Development Mindset

Use this skill early for programming tasks, especially when the user has not provided detailed project conventions. Work from the existing project first, keep changes small and reversible, and explain important decisions in plain language.

## Core Mindset

- Respect the existing project first.
- Read before changing.
- Do not overwrite existing files without checking their content.
- Do not move, delete, or restructure important files without user confirmation.
- Prefer small, reversible changes.
- Keep documentation synchronized with code.
- Always consider testing before declaring work complete.
- Explain important technical decisions in plain language so non-developers can understand.
- Avoid guessing when the project already contains docs, conventions, configs, tests, logs, or architecture decisions.
- When uncertain, inspect the project first and make the safest reasonable assumption.
- Ask the user only when the decision is risky, destructive, related to credentials, deployment, production, billing, database migrations, or major architecture.

## Optional Same-Repository Skills

Reference other skills only when they exist in the same shared skills repository as this skill.

Before using an optional skill:
1. Locate this skill in the shared repository.
2. Verify that the sibling skill folder exists and contains a valid `SKILL.md`, such as `../documentation-guidelines/SKILL.md` from this skill folder or `skills/documentation-guidelines/SKILL.md` from the repository root.
3. If the skill is missing, tell the user the optional skill was not found in the shared repository and use the fallback instructions in this skill.

Optional skills to check before use:

- `documentation-guidelines`: use for feature, module, backend, and API documentation. Fallback: use the documentation structure and content checklist below.
- `design-system-generator`: use for creating or updating `docs/DESIGN_SYSTEM.md`. Fallback: create a practical design system document manually.
- `agents-md-generator`: use for creating or updating `AGENTS.md`, `CLAUDE.md`, or equivalent project memory files. Fallback: create or update those files manually.
- `vps-docker-traefik-deploy`: use for VPS, Docker Compose, and Traefik deployment planning or implementation. Fallback: provide general deployment guidance manually.

Do not reference, require, download, or depend on external skills or user-specific local paths.

## General Workflow

### 1. Discover

- Inspect the repository structure.
- Identify the tech stack, framework, package manager, test tooling, build tooling, deployment files, and documentation.
- Look for `README.md`, `docs/`, `AGENTS.md`, `CLAUDE.md`, package files, lock files, framework configs, Docker files, CI files, and existing tests.
- In multi-repository projects, check related repositories when the task clearly spans backend, frontend, API, admin panel, worker, mobile app, or deployment.

### 2. Understand

- Read existing documentation before changing code.
- Read relevant source files before proposing changes.
- Look for business rules and special project-specific behavior.
- Do not replace unique business logic with generic assumptions.

### 3. Plan

- Create a short implementation plan for substantial tasks.
- Mention files likely to change.
- Mention the testing strategy.
- For non-developers, explain the plan in simple language.

### 4. Implement

- Follow existing architecture, naming conventions, coding style, framework standards, and package manager conventions.
- Prefer minimal changes that solve the task.
- Do not introduce unnecessary new libraries.
- Use official documentation or local project conventions when working with frameworks or third-party libraries.

### 5. Test

- Run the most relevant targeted tests first.
- Then run the full available test suite when practical.
- If tests fail, fix the issue and rerun.
- If full tests cannot be run, clearly explain why and provide the closest reliable verification.

### 6. Document

- Update relevant documentation after code changes.
- Update feature docs, module docs, `README.md`, `AGENTS.md`, or `CLAUDE.md` when project behavior or instructions changed.
- Document difficult bugs and their solutions so the project does not repeat the same problem later.

### 7. Report

- Summarize what changed.
- List tests or checks that were run.
- Mention documentation updated.
- Mention anything that could not be verified.
- Mention remaining risks or recommended next steps.

## New Project Workflow

Use this when the project is empty, newly created, or still choosing a stack.

Create these folders and files when they do not already exist:

- `README.md`
- `docs/`
- `docs/README.md`
- `deploy/`
- `deploy/README.md`
- `src/` when appropriate for the selected stack

For frameworks that use a different standard source folder, such as `app/`, `pages/`, `packages/`, `backend/`, `frontend/`, `cmd/`, `internal/`, or another framework-specific structure, respect the framework standard. Do not force all source code into `src/` if that would conflict with the stack.

For a new project:

- Help the user choose a suitable tech stack if they have not chosen one.
- Explain tradeoffs in plain language.
- Recommend a simple, maintainable structure.
- Initialize documentation early.
- Create a `README.md` that explains project purpose, setup, development, testing, and deployment basics.
- Create `docs/README.md` as the documentation entry point.
- Create `deploy/README.md` as the deployment entry point.
- Check whether Git is installed.
- If Git is installed, initialize Git when appropriate and safe.
- If Git is not installed, guide the user to install it. Do not attempt system-level installation without user confirmation.
- Ask whether the user wants GitHub, GitLab, Bitbucket, or another Git hosting provider for safe remote backup.
- Do not create remotes, push code, or configure credentials without user confirmation.

## Existing Project Workflow

Use this when the project already contains source code, configs, docs, or deployment files.

Create these folders and files only if missing and safe:

- `README.md`
- `docs/`
- `docs/README.md`
- `deploy/`
- `deploy/README.md`

For `src/`:

- Do not force-create or migrate to `src/` if the project already has a framework-standard source structure.
- Create `src/` only when the project has no clear source folder and `src/` would improve clarity.
- Never move existing code into `src/` without user confirmation.

## Documentation Structure

Use `docs/features/` for feature and module documentation.

Recommended structure:

```text
docs/
  README.md
  DESIGN_SYSTEM.md
  features/
    customer/
      README.md
      customer-module.md
      customer-payment.md
    order/
      README.md
      order-module.md
      order-fulfillment.md
```

Rules:

- Give each major business module its own folder under `docs/features/`.
- Put a `README.md` in each module folder.
- Link from the module `README.md` to all child documents in that module.
- Keep related docs together.
- Use clear file names such as `customer-module.md`, `customer-payment.md`, and `customer-notifications.md`.
- Keep docs practical, not theoretical.

When writing module docs, include:

- Module purpose
- Main user flows
- Important business rules
- Related source files
- Related API endpoints, pages, components, jobs, commands, database tables, or services
- Special project-specific behavior
- Edge cases
- Known limitations
- Testing notes
- Deployment or configuration notes when relevant
- Links to child docs or related module docs

Use `documentation-guidelines` only if it exists in the same shared skills repository. Otherwise, use this section as the fallback.

## Design System

For projects with UI, create or update `docs/DESIGN_SYSTEM.md`.

Use `design-system-generator` only if it exists in the same shared skills repository. Otherwise, create a practical `DESIGN_SYSTEM.md` manually with:

- Layout