Skip to content

Commit fd50264

Browse files
apiadapiad
committed
chore(knowledge): add notes and plans
- Add funny-coding-quotes.md - Add random-thoughts.md - Add microcli-implementation.md - Remove auth-thoughts.md (stale)
1 parent 2f32225 commit fd50264

File tree

4 files changed

+199
-12
lines changed

4 files changed

+199
-12
lines changed

‎.knowledge/notes/auth-thoughts.md‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎.knowledge/notes/funny-coding-quotes.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Funny Coding Quotes
3+
slug: funny-coding-quotes
4+
date: 2026-03-27
5+
tags: [humor, quotes, coding]
6+
---
7+
8+
# Funny Coding Quotes
9+
10+
A collection of humorous observations about the software development experience.
11+
12+
---
13+
14+
## The Reality
15+
16+
> "It works on my machine." — Every developer, ever
17+
18+
> "There are only two hard things in computer science: cache invalidation, naming things, and off-by-one errors." — Phil Karlton (paraphrased)
19+
20+
> "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." — Brian Kernighan
21+
22+
---
23+
24+
## The Process
25+
26+
> "First, solve the problem. Then, write the code." — John Johnson
27+
28+
> "Code is read more often than it is written. Make it readable." — Ancient developer proverb
29+
30+
> "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler
31+
32+
---
33+
34+
## The Stack Overflow Experience
35+
36+
> "I have no idea what I did, but I take full credit for it." — Post-stackoverflow copy-paste developer
37+
38+
> "It works... but I don't know why." — Every programmer after fixing a bug by accident
39+
40+
---
41+
42+
## The Meeting
43+
44+
> "We need to restructure our codebase." — What managers say when they want to add more meetings
45+
46+
> "It's not a bug, it's an undocumented feature."
47+
48+
---
49+
50+
## The Documentation
51+
52+
> "Documentation? I'll do it later." — Famous last words
53+
54+
> "In theory, there is no difference between theory and practice. In practice, there is." — Jan L. A. van de Snepscheut
55+
56+
---
57+
58+
*Collected for the sanity of all developers who have ever stared at their screen in disbelief.*

‎.knowledge/notes/random-thoughts.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Random Thoughts
3+
slug: random-thoughts
4+
date: 2026-03-27
5+
tags: [musings, observations]
6+
---
7+
8+
# Random Thoughts
9+
10+
## On Productivity
11+
12+
The best to-do list is the one you don't need to check. There's something elegant about knowing your next action without having to look it up. Context matters more than we admit.
13+
14+
## On Writing
15+
16+
First drafts are just the author telling themselves the story. Editing is where you start telling it to the reader. Most people confuse these phases.
17+
18+
## On Tools
19+
20+
We spend more time choosing our tools than mastering them. The hammer that takes an hour to find is worthless even if it's the best hammer.
21+
22+
## On Learning
23+
24+
You don't understand something until you've taught it. Not just read it, not just done it—taught it. The gaps in your knowledge become obvious when you try to explain.
25+
26+
## On Attention
27+
28+
Focus isn't about doing one thing—it's about actively ignoring everything else. That's the hard part. The doing is easy; the not-doing-else is where the work is.
29+
30+
## On Complexity
31+
32+
Most problems aren't complex—they're complicated. Complex means you can't predict the outcome. Complicated just means there are many parts. We confuse these constantly and over-engineer simple things.
33+
34+
## On Decision Making
35+
36+
The decision to start is often more important than the quality of the start. Motion beats contemplation every time.

‎.knowledge/plans/microcli-implementation.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
id: microcli-implementation
3+
created: 2026-03-27
4+
modified: 2026-03-27
5+
type: plan
6+
status: active
7+
expires: 2026-04-03
8+
---
9+
10+
# Plan: Build microcli
11+
12+
## Context
13+
14+
Create a single-file Python CLI framework (~400 lines) for AI-friendly micro CLI apps. Goals:
15+
- Single `.py` file, standard library + pyyaml
16+
- Annotated type hints for docs/args
17+
- High-level `sh()` for shell commands
18+
- `--dry-run` mode
19+
- `command.explain()` for agent workflows
20+
21+
## Phases
22+
23+
### Phase 1: Core Framework
24+
**Goal:** Build the command registration and argument parsing system
25+
26+
**Deliverable:** `microcli.py` with `@m.command` decorator
27+
28+
**Done when:**
29+
- [ ] `@m.command` decorator registers functions
30+
- [ ] Annotated type hints parsed into argparse
31+
- [ ] Module docstring used as help text
32+
- [ ] Function docstring printed before execution
33+
- [ ] `m.Flag` type marker works
34+
- [ ] `--help` works at module and command level
35+
- [ ] `--dry-run` flag works globally
36+
37+
### Phase 2: Shell & Status
38+
**Goal:** Implement `m.sh()` and status helpers
39+
40+
**Deliverable:** Working shell executor with Result object
41+
42+
**Done when:**
43+
- [ ] `m.sh(cmd)` executes and returns `Result`
44+
- [ ] `Result` has: ok, failed, stdout, stderr, returncode, duration
45+
- [ ] `--dry-run` makes `sh()` print command instead of executing
46+
- [ ] `m.ok()`, `m.fail()`, `m.info()`, `m.step()`, `m.warn()` work
47+
- [ ] `m.fail()` exits with code 1
48+
49+
### Phase 3: Utilities
50+
**Goal:** Implement file/path utilities
51+
52+
**Deliverable:** Core utility functions
53+
54+
**Done when:**
55+
- [ ] `m.read(path)` returns file contents
56+
- [ ] `m.write(path, content)` writes file
57+
- [ ] `m.ls(path=".")` returns list of filenames
58+
- [ ] `m.glob(pattern)` returns list of Paths
59+
- [ ] `m.touch(path)`, `m.rm(path)`, `m.cp(src,dst)`, `m.mv(src,dst)`
60+
- [ ] `m.cd(path)` works as context manager
61+
- [ ] `m.which(cmd)` returns Path or None
62+
- [ ] `m.env(name)` returns env var or None
63+
64+
### Phase 4: Command Explain
65+
**Goal:** Implement `command.explain()` for agent workflows
66+
67+
**Deliverable:** Command invocation generator
68+
69+
**Done when:**
70+
- [ ] `cmd.explain()` generates `python app.py cmd`
71+
- [ ] `cmd.explain(arg=value)` includes positional args
72+
- [ ] `cmd.explain(flag=True)` includes `--flag`
73+
- [ ] Missing required args raises TypeError
74+
- [ ] Optional args with defaults work
75+
76+
### Phase 5: YAML Support
77+
**Goal:** Add YAML parsing utilities
78+
79+
**Deliverable:** `m.yaml` module
80+
81+
**Done when:**
82+
- [ ] `m.yaml.load(text)` parses YAML
83+
- [ ] `m.yaml.dump(data)` serializes to YAML
84+
85+
## Success Criteria
86+
87+
- [ ] Single file, ~400 lines
88+
- [ ] Works with `python app.py --help`
89+
- [ ] `m.sh()` works in both normal and dry-run modes
90+
- [ ] `cmd.explain(arg=val)` generates correct invocation
91+
- [ ] All utilities return values (not print)
92+
- [ ] Status helpers print to stdout
93+
- [ ] Annotated type hints become help text
94+
95+
## Risks & Mitigations
96+
97+
| Risk | Likelihood | Mitigation |
98+
|------|------------|------------|
99+
| argparse + dry-run interaction complex | Medium | Test both modes early |
100+
| Type hint parsing edge cases | Medium | Start simple, add as needed |
101+
| Single file too long | Low | Keep under 500 lines |
102+
103+
## Related
104+
105+
- Design: `.knowledge/notes/mode-command-tool-pattern.md`

0 commit comments

Comments
 (0)