diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..6e120d0 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +# EditorConfig helps maintain consistent coding styles +root = true + +[*] +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 + +[*.md] +# Keep Markdown tidy; code blocks remain untouched by trim rule exceptions +trim_trailing_whitespace = true diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..21e3a61 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# Require review from maintainers for key areas +* @iplaycomputer + +# Optional: expand with more granular ownership as project grows +# /kb/ @iplaycomputer +# /labs/ @iplaycomputer +# /tickets/ @iplaycomputer +# /scenarios/ @iplaycomputer diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 62165da..1540d69 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,13 +12,32 @@ Briefly describe what this PR adds or changes. - [ ] Uses the correct template (copied from 000.*-template.md) - [ ] Clear, reproducible steps and plain language - [ ] Relative links resolve inside the repo + - [ ] Avoid duplication across modules (KB = productized steps; Lab = full commands + Verification; Scenario = flow/success, links only) + - [ ] Deep link to sections where applicable (KB → #resolution-steps, Lab → #verification) - Metadata - [ ] Owner set; Last Reviewed and Next Review Due (KB/Lab) - [ ] Escalation Path filled (Ticket) - [ ] Metrics block added if useful (see docs/METRICS.md) - Quality - [ ] Verification steps included (expected outputs / pass-fail) + - [ ] Anchors exist and resolve (KB “Resolution Steps”, Lab “Verification”) - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria +### Labs (if included) +- [ ] Dedicated “Verification” section with expected outputs +- [ ] Images pinned if using containers; HTTP services include a simple healthcheck when applicable +- [ ] Assets stored under `labs//assets/` + +### KBs (if included) +- [ ] Brief (1–2 lines) verification; link to related Lab for full commands + +### Scenarios (if included) +- [ ] Uses deep links to KB “Resolution Steps” and Lab “Verification” (no step duplication) + ## Notes Add screenshots, logs, or context as needed. + +## How to Verify (for reviewers) +- Click Related KB/Lab links and confirm they jump to the correct anchors. +- If a Lab changed, run the Verification steps and confirm expected outputs. +- Check that no personal IPs or credentials are included; use `` placeholders. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a1a3fa1..fceefc7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -3,6 +3,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents should prioritize clarity, reproducibility, and alignment with the troubleshooting standards in `CONTRIBUTING.md`. ## Big Picture + - Four modules map to real workflows: - Tickets (`/tickets/`): user-reported issues - Knowledge Base (`/kb/`): solution docs derived from tickets @@ -11,6 +12,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - Use templates in each folder (`000.*-template.md`). ## Key Files + - `CONTRIBUTING.md`: Primary standards, workflows, and references (CompTIA A+ model, escalation, templates). - `docs/lamp-osticket-setup.md`: Optional local osTicket setup to test tickets/KBs. - `docs/ROLES.md`: Lightweight tiers, escalation cues, and ownership metadata. @@ -18,6 +20,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - `README.md`: Project overview and contribution on-ramp. ## Authoring Patterns + - Follow CompTIA A+ 6-step model: Identify → Theory → Test → Plan/Implement → Verify → Document. - Keep language plain and steps reproducible. Include environment details (OS/version), verification, and escalation path. - Link artifacts with relative paths (e.g., `/tickets/printer-failure.md` in KB/Lab/Scenario). @@ -28,20 +31,24 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - Scenarios should express flow and success criteria, linking to KB "Resolution Steps" and Lab "Verification" sections (use deep links like `/kb/foo.md#resolution-steps` and `/labs/bar.md#verification`). ## Workflows + - Propose in Discussions: draft tickets/KBs/labs in appropriate categories. - Land changes via PRs adding Markdown under `/tickets`, `/kb`, `/labs`, `/scenarios`. - Labs should be verifiable on a Linux VM or container; osTicket is optional. ## Examples from Repo + - Templates: `kb/000.kb-template.md`, `labs/000.lab-template.md`, `tickets/000.ticket-template.md`, `scenarios/000.scenario-template.md`. - osTicket URLs referenced use `http:///osticket/` and `.../scp` for staff; replace `` locally and do not share it publicly. ## Conventions + - Filenames: use kebab-case, concise, and descriptive (e.g., `printer-spooler-restart.md`). - Metadata blocks: include Category, Environment, Owner, Reviewed dates when applicable. - References: cite external docs in a final section; prefer vendor support links. ## What NOT to do + - Don’t invent infrastructure or public endpoints; this repo is markdown-only. - Don’t add personal IPs or credentials. diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 0000000..32cbb04 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,19 @@ +name: markdownlint + +on: + pull_request: + push: + branches: [ main ] + +jobs: + lint: + name: lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v16 + with: + globs: | + **/*.md diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..835920e --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,6 @@ +{ + // Inherit rules from .markdownlint.jsonc and set default globs + "config": ".markdownlint.jsonc", + "globs": ["**/*.md"], + "ignores": ["**/node_modules/**", ".git/**"] +} diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 0000000..56ac331 --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,8 @@ +{ + // Allow long lines in code blocks and tables + "MD013": false, + // Allow consecutive headings in templates/checklists + "MD025": false, + // Allow inline HTML when needed (README badges) + "MD033": false +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..f6fc268 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,8 @@ +{ + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + "files.eol": "\n", + "[markdown]": { + "editor.formatOnSave": true + } +} \ No newline at end of file diff --git a/labs/htpasswd-auth-reset.md b/labs/htpasswd-auth-reset.md index bb6d871..72adc62 100644 --- a/labs/htpasswd-auth-reset.md +++ b/labs/htpasswd-auth-reset.md @@ -42,12 +42,13 @@ Simulate a credential reset and prove the fix with a protected endpoint. # Expect 200 ``` - ## Verification - ```powershell +## Verification + +```powershell $pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode # Expect: 200 - ``` +``` ## Cleanup ```powershell diff --git a/labs/mailhog-connectivity.md b/labs/mailhog-connectivity.md index 1077a3b..8699374 100644 --- a/labs/mailhog-connectivity.md +++ b/labs/mailhog-connectivity.md @@ -45,11 +45,12 @@ Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. 5) Verify in UI - Browse http://localhost:8025 and confirm the message is present. - ## Verification - ```powershell +## Verification + +```powershell Invoke-WebRequest http://localhost:8025 -UseBasicParsing | Select-Object -ExpandProperty StatusCode # Expect: 200 (and message visible in UI) - ``` +``` ## Cleanup ```powershell diff --git a/labs/print-queue-stuck.md b/labs/print-queue-stuck.md index 797c865..99a6171 100644 --- a/labs/print-queue-stuck.md +++ b/labs/print-queue-stuck.md @@ -52,11 +52,12 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo docker exec print-queue cat /queue/processed.txt ``` - ## Verification - ```powershell +## Verification + +```powershell docker exec print-queue cat /queue/processed.txt # Expect: remaining job name present; queue stable - ``` +``` ## Cleanup ```powershell diff --git a/labs/resource-spike-triage.md b/labs/resource-spike-triage.md index 89b4ecb..1a75242 100644 --- a/labs/resource-spike-triage.md +++ b/labs/resource-spike-triage.md @@ -41,11 +41,12 @@ Practice identifying and resolving resource spikes that cause slowness. # Expect CPU usage back to normal ``` - ## Verification - ```bash +## Verification + +```bash top -b -n 1 | head -n 20 # Expect: CPU/Disk normalized; no stress-ng running - ``` +``` ## Cleanup ```bash diff --git a/scenarios/README.md b/scenarios/README.md index fb778fb..fb59a46 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -3,6 +3,7 @@ End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the story and define success criteria. - Template: [000.scenario-template.md](./000.scenario-template.md) + - Good scenarios include: - A realistic ticket with symptoms and constraints - A KB solution path with alternatives @@ -10,5 +11,7 @@ End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the stor - Clear acceptance/success criteria Conventions: + - Name scenarios clearly (e.g., `printer-spooler-end-to-end.md`). - Link artifacts with relative paths; avoid external private endpoints. + diff --git a/scenarios/account-lockout-reset.md b/scenarios/account-lockout-reset.md index d294760..50f3cdf 100644 --- a/scenarios/account-lockout-reset.md +++ b/scenarios/account-lockout-reset.md @@ -1,8 +1,8 @@ # Scenario: Account lockout and password reset - Related Ticket: /tickets/account-locked-out.md -- Related KB: /kb/account-lockout-reset.md -- Related Lab: /labs/htpasswd-auth-reset.md +- Related KB: /kb/account-lockout-reset.md#resolution-steps +- Related Lab: /labs/htpasswd-auth-reset.md#verification ## Flow 1. User reports lockout; verify identity and account status. diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index 4a8a87b..04d5af3 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -1,14 +1,17 @@ # Scenario: Outlook reconnect after update - Related Ticket: /tickets/outlook-disconnected-password-prompts.md -- Related KB: /kb/outlook-reconnect-after-update.md -- Related Lab: /labs/mailhog-connectivity.md +- Related KB: /kb/outlook-reconnect-after-update.md#resolution-steps +- Related Lab: /labs/mailhog-connectivity.md#verification ## Flow 1. Validate credentials on another system; check VPN if remote. 2. Confirm connectivity; recreate profile or clear cached credentials as needed. 3. In lab, use MailHog to verify SMTP is reachable and a test message is captured. + ## Success Criteria +- - MailHog shows the test message; service reachable. - Ticket notes profile/cache actions; KB drafted with steps. + diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index ed97ec3..2d14b4d 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -1,14 +1,17 @@ # Scenario: Department-wide printer outage (queue clearing) - Related Ticket: /tickets/cannot-print-to-shared-printer.md -- Related KB: /kb/printer-queue-clearing.md -- Related Lab: /labs/print-queue-stuck.md +- Related KB: /kb/printer-queue-clearing.md#resolution-steps +- Related Lab: /labs/print-queue-stuck.md#verification ## Flow 1. Confirm scope (multiple users); check server queue/state. 2. Clear stuck job(s); restart the service. 3. In lab, simulate stuck queue; clear oldest job; restart consumer. + ## Success Criteria +- - Queue shows processed jobs and accepts new test job. - Ticket documents scope, remediation, and server-side action; KB drafted. + diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index 3105810..07c650b 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -1,14 +1,17 @@ # Scenario: Workstation performance triage - Related Ticket: /tickets/computer-running-slow-lagging.md -- Related KB: /kb/workstation-performance-triage.md -- Related Lab: /labs/resource-spike-triage.md +- Related KB: /kb/workstation-performance-triage.md#resolution-steps +- Related Lab: /labs/resource-spike-triage.md#verification ## Flow 1. Compare internal vs external latency; check local resource usage. 2. Identify culprit (scan/update/runaway process); apply remediation. 3. In lab, trigger and stop a synthetic load; verify usage returns to normal. + ## Success Criteria +- - CPU/Disk usage normalizes; simple command completes fast. - Ticket lists root cause and remediation; KB drafted. + diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index 8864eb3..6897c15 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -5,18 +5,26 @@ **Impact:** Single user | Department | Organization-wide **Urgency:** Low (no workflow impact) | Medium (work slowed) | High (work blocked) -**Problem:** [One-line description of the issue] -**Symptoms:** [What the user sees or experiences] -**Environment:** [OS, system, or software version] +## Problem +[One-line description of the issue] + +## Symptoms +[What the user sees or experiences] + +## Environment +[OS, system, or software version] + +## Troubleshooting Steps Taken -**Troubleshooting Steps Taken:** - [ ] [Step 1, e.g., "Checked printer connection"] - [ ] [Step 2, e.g., "Restarted Print Spooler service"] -**Resolution:** -[Steps to resolve, or "TBD" if unknown] +## Resolution +[Steps to resolve, or "TBD" if unknown] + +## Escalation Path -**Escalation Path:** - [ ] Tier 1 complete (basic troubleshooting done) - [ ] Escalated to Tier 2 (e.g., for driver issues) - [ ] Escalated to Tier 3 (e.g., for hardware replacement) + diff --git a/tickets/README.md b/tickets/README.md index e9492ec..400be77 100644 --- a/tickets/README.md +++ b/tickets/README.md @@ -3,18 +3,22 @@ User-reported issues. Start here when simulating a helpdesk intake. - Template: [000.ticket-template.md](./000.ticket-template.md) + - How to write good tickets: - Be specific about symptoms, environment, and what changed. - Include simple reproduction steps if known. - Avoid credentials or personal IPs. Conventions: + - Use kebab-case filenames (e.g., `printer-wont-print.md`). - Link related KBs/labs/scenarios with relative paths. - Follow the CompTIA A+ 6-step model in your troubleshooting notes. Examples: + - [Account locked out – cannot log in](./account-locked-out.md) - [Cannot print to shared Finance printer](./cannot-print-to-shared-printer.md) - [Outlook disconnected and password prompts](./outlook-disconnected-password-prompts.md) - [Computer is running extremely slow / lagging](./computer-running-slow-lagging.md) + diff --git a/tickets/account-locked-out.md b/tickets/account-locked-out.md index 9f6fe54..626b3ff 100644 --- a/tickets/account-locked-out.md +++ b/tickets/account-locked-out.md @@ -17,6 +17,7 @@ **Environment:** Windows desktop joined to AD; remote services (email/VPN) affected. **Troubleshooting Steps Taken:** +- - [ ] Verified user identity via secondary info (DOB, employee ID) - [ ] Checked AD status for JDoe - [ ] If locked, unlocked account @@ -27,6 +28,8 @@ [TBD] **Escalation Path:** +- - [ ] Tier 1 complete (basic checks and unlock/reset) - [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) - [ ] Escalated to Tier 3 (directory service problems) + diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 1631e7c..7f51f9c 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -17,6 +17,7 @@ **Environment:** Windows clients printing via central print server. **Troubleshooting Steps Taken:** +- - [ ] Confirmed print server is running and reachable - [ ] Remotely checked client printer driver/port - [ ] Cleared local print queue; attempted test page @@ -27,6 +28,8 @@ [TBD] **Escalation Path:** +- - [ ] Tier 1 complete (client/queue verification) - [ ] Escalated to Tier 2 (server-side queue/driver) - [ ] Escalated to Tier 3 (hardware/network issue) + diff --git a/tickets/computer-running-slow-lagging.md b/tickets/computer-running-slow-lagging.md index 1d06fe8..ce05d6f 100644 --- a/tickets/computer-running-slow-lagging.md +++ b/tickets/computer-running-slow-lagging.md @@ -16,7 +16,8 @@ **Symptoms:** Long app launch times; constant disk activity; internal company site loads slowly while YouTube is fine. **Environment:** Windows 10 desktop; corporate network. -**Troubleshooting Steps Taken:** +## Troubleshooting Steps Taken + - [ ] Compared internal vs external network latency (ping tests) - [ ] Checked Task Manager CPU/RAM/Disk usage and processes - [ ] Ran malware scan or checked for runaway updates @@ -26,7 +27,9 @@ **Resolution:** [TBD] -**Escalation Path:** +## Escalation Path + - [ ] Tier 1 complete (resource & basic network checks) - [ ] Escalated to Tier 2 (network/server) - [ ] Escalated to Tier 3 (hardware upgrade/policy) + diff --git a/tickets/outlook-disconnected-password-prompts.md b/tickets/outlook-disconnected-password-prompts.md index 66e8da5..8b6a02b 100644 --- a/tickets/outlook-disconnected-password-prompts.md +++ b/tickets/outlook-disconnected-password-prompts.md @@ -16,7 +16,8 @@ **Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. **Environment:** Laptop (potentially remote); VPN in use when offsite. -**Troubleshooting Steps Taken:** +## Troubleshooting Steps Taken + - [ ] Verified credentials work on another system (e.g., internal portal) - [ ] Checked Outlook status bar connectivity - [ ] Verified VPN connection if remote @@ -26,7 +27,9 @@ **Resolution:** [TBD] -**Escalation Path:** +## Escalation Path + - [ ] Tier 1 complete (profile/credentials checks) - [ ] Escalated to Tier 2 (Exchange/Autodiscover) - [ ] Escalated to Tier 3 (SAML/MFA/identity provider) +